---
updatedAt: 2026-09-01T19:51:06.000Z
agentTools:
  projectIndex: https://docs.uplynk.com/llms.txt
---

# Automate via Slicebot

Slicebot monitors directories for new files and automatically slices and uploads them to the cloud.

Slicebot monitors one or more directories for new files. Once it detects a file, it automatically slices and uploads it to the cloud.

<Callout icon="📘" theme="info">
   Slicebot is included with the Slicer installation and it is not officially supported on Windows.
</Callout>

## Quick Start

Setting up Slicebot requires two steps:

1. Create a configuration file that defines the directories to monitor and how content will be processed.
2. Start Slicebot by running the following command: `./slicebot /ConfigurationFilePath`

## Basic Information

This section explains:

* The available [configuration](#configuration) methods.
* How to set up the [main Slicebot configuration file](#main-configuration-file).
* How to set up a [file-specific configuration file](#file-specific-configuration-file).
* How to define configuration settings within a [file name](#file-name-configuration).
* How to [test](#testing) a configuration.
* How to [end a Slicebot session](#end-a-slicebot-session).

## Configuration

Configuration settings may be defined through the following mechanisms:

* [**Main Configuration File**](#main-configuration-file)

  * Defines a default configuration.
  * Identifies the set of directories to monitor.
  * Defines directory-specific configurations.

* [**File-specific Configuration File**](#file-specific-configuration-file): Defines how a specific file will be processed.

* [**File Name**](#file-name-configuration): Defines how a specific file will be processed.

**Settings will be applied in the following order:**

1. \[Global] section of the main configuration file.
2. Directory-specific sections in the main configuration file.
3. File-specific configuration file.
4. File name.

Settings defined within a file name take precedence over any conflicting settings defined elsewhere.

### Main Configuration File

Slicebot requires a configuration file that defines:

* How and when source media will be processed.
* The directories that will be monitored for source media.

[View configuration settings](#configuration-settings).

**Key Information:**

* Upon starting Slicebot, you must [specify the location of this configuration file](#quick-start).
* Create this configuration file using a text editor.
  * The file extension should be "cfg" in lower-case (e.g., `slicebot.cfg`).
  * This configuration file may be saved in any directory accessible by Slicebot.

**Categorize settings into the following sections:**

* **Global**: Defines a default configuration for all monitored directories.

* **Directory-specific Settings**: A section must be created for each desired monitored directory.

  * The header for this type of section should be set to the full path to the desired directory.

    **Example:**

    ```ini
    [~/sales/videos/2016/]
    ```

* The settings defined in this type of section:
  * Only apply to that directory.
  * Override any conflicting settings defined in the Global section.

* A section may be left blank. A blank section indicates that the specified directory will be monitored and processed according to the configuration defined in:
  * The `Global` section of the main configuration file.
  * A file-specific configuration file.
  * A file name.

**Define settings** using the following format: `Name = Value`

**Sample Configuration**

```ini
[global]
enc_wait = 1
mail_host = smtp.gmail.com:587
done_emails = sys@mycompany.com, me@mycompany.com
fail_emails = me@mycompany.com
[~/t/slice/a/]
[~/t/slice/b/]
enc_wait = 0
username = me@email.com
apikey = abcDEFghiJKLmnoPQRtuvWXYz123ABCdefGHIJKL
```

### File-Specific Configuration File

You can define how a specific file is processed by creating a configuration file that contains the desired settings.

<Callout icon="📘" theme="info">Although most [configuration settings](#configuration-settings) may be defined within a file-specific configuration, there are exceptions (e.g., halt_on_error and ignore). The description associated with each setting indicates any limitations on where it may be implemented.</Callout>

**Key information**

* File-specific settings may be defined in a text file that meets the following conditions:

  * It must be stored in the same directory as the desired source media.
  * It must be named after the desired source media file.
  * The file extension should be "cfg" in lower-case (e.g., myvideo.mp4.cfg).

    Use the [`helper_noext`](#configuration-settings) setting to exclude the source media's file extension (e.g., mp4).

* This type of configuration file should not contain section headers (e.g., \[global] or \[\~/folder/]).

* File-specific settings override conflicting settings defined in the [main configuration file](#main-configuration-file).

* As a best practice, ensure that a file-specific configuration file is present in a monitored directory before copying the corresponding media file into it. This ensures proper processing according to the file-specific configuration.

* Define the [require\_config](#configuration-settings) setting within the main configuration file to require a file-specific configuration before processing a file.

A sample configuration file is provided below.

```ini
enc_wait = 0
done_emails = marketing@mycompany.com, joe@mycompany.com
fail_emails = jane@mycompany.com
```

### File Name Configuration

You can define how a specific file is processed by including the desired settings within the source media's file name.

Slicebot only honors settings defined within a file name when the [`allow_inline` setting](#configuration-settings) has been enabled via either the main or a [file-specific configuration file](#file-specific-configuration-file).

<Callout icon="📘" theme="info">Although most configuration settings may be defined within a file name, there are exceptions (e.g., halt_on_error and ignore). The description associated with each setting indicates any limitations on where it may be implemented.</Callout>

****Syntax****: `FileName^Setting1=Value1^Setting2=Value2^SettingN=ValueN.ext`

**Example**

Original file name: `marketing.mp4`

New file name: `marketing^max_slices=3^external_id=1FA1272b.mp4`

Follow these guidelines when defining a setting within a file name:

* Append each setting to the file name.

* Prepend each setting with a caret (^) symbol.

* A file name should never contain spaces.

  * Convert space characters within a setting's value to the plus (+) symbol.

    **Example**: `my_movie^description=Standard+Trailer.mp4`

    In the above example, the asset's name will be set to "Standard Trailer."

* A matching file name must still be assigned to any supporting files (e.g., closed captioning or file-specific configuration file).

  **Closed Captioning Example**: `my_movie^max_slices=3^external_id=1FA1272b.mp4.ttml`

  The [`helper_noext`](#configuration-settings) setting determines whether the source media's file extension (e.g., mp4) needs to be included when naming supporting files.

* Settings defined within a file name override conflicting settings defined in the Slicebot or a file-specific configuration file.

* Avoid creating file names longer than those supported by the OS.

<Callout icon="💡" theme="success">Use [file-specific configuration files](#file-specific-configuration-file) to avoid OS limitations.</Callout>

### Testing

Use the `--dry-run` option to test your configuration without processing files.

`./slicebot --dry-run slicebot.cfg`

### End a Slicebot Session

Slicebot runs indefinitely until one of the following conditions is true:

* It is manually interrupted. The recommended method is to send the SIGINT signal, which allows Slicebot to finish the current slicing job before shutting down. Send this signal by running the following command: `kill -SIGINT SlicebotPID`
* Slicebot encounters a fatal error and exits with a non-zero code. This may occur when there is an issue with the configuration file.

## Configuration Settings

This section describes the supported configuration settings that control how Slicebot processes files.

**Key information**

* Lines starting with # in the config file are treated as comments and ignored.
* Although most settings can be used anywhere (global section, directory sections, or per-file configs), some settings are more naturally suited to certain locations. For example, the global section typically holds username, API key, and email settings, although they are valid in other locations as well.
* Setting values support basic value substitution:

  \[FILENAME] - replaced with the current source filename, minus the path. Example, with a source file of /mnt/files/ad.mp4:<br />\
  external\_id=foo\[FILENAME]bar<br />would become<br />external\_id=fooad.mp4bar

  \[FILENAME\_SHORT] - replaced with the current source filename, minus the path and file extension. Example, with a source file of /mnt/files/ad.mp4:<br />external\_id=foo\[FILENAME\_SHORT]bar<br />would become<br />external\_id=fooadbar

The following configuration settings may be leveraged when defining:

* [The main configuration file](#main-configuration-file).
* [A file-specific configuration file](#file-specific-configuration-file).
* [Configuration settings by file name](#file-name-configuration).

### Slicebot-Only Settings

The following settings apply exclusively to Slicebot and are not available for the standalone VOD Slicer.

| Setting             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Example                                                 |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| allow\_inline       | **Directory Monitoring**<br />Determines whether the source media's file name may contain configuration settings. [Learn more](#file-name-configuration).<br /><br />**Valid values are**:<ul><li>**1 \| true**: Indicates that the file name may contain configuration settings.</li><li>**0 \| false**: Indicates that settings defined within the file name will be ignored.</li></ul>**Default value**: 1                                                                                                                                           | `allow_inline = 0`                                      |
| auto\_replace       | **Asset Replacement (Library)**<br />Determines whether asset(s) with the same external ID will be automatically replaced.<br /><br />**Valid values are**:<ul><li>**1 \| true**: Ensures that the external ID assigned to an asset starts with `_replace`. This will cause it to replace existing assets with the same external ID.</li><li>**0 \| false**: Indicates that the external ID assigned to an asset will not be modified.</li></ul>                                                                                                        | `auto_replace = 1`                                      |
| done\_directory     | **Post-Processing**<br />Defines the directory to which the source media will be moved after it has been successfully processed.<br /><br />**Key information**:<ul><li>If the specified directory does not exist, it will be created.</li><li>After successful processing, the source media will be deleted if either:<ul><li>This setting has not been defined, or</li><li>This setting is set to `none`.</li></ul></li></ul>**Syntax**: `done_directory = none`                                                                                      | `done_directory = ~/media/success`                      |
| done\_emails        | **Notifications**<br />Comma-separated list of email addresses to notify when a file is successfully processed. Requires `mail_host`.                                                                                                                                                                                                                                                                                                                                                                                                                   | `done_emails = fred@gmail.com, george@example.com`      |
| done\_url           | **Notifications**<br />Defines the URL to which an HTTP `POST` request is submitted when a file is successfully processed. [Learn more](#http-notifications).                                                                                                                                                                                                                                                                                                                                                                                           | `done_url = http://myserver.net/myservice`              |
| fail\_directory     | **Post-Processing**<br />Directory to move source media to when processing fails.<br /><br />**Key information**:<ul><li>If the directory does not exist, it will be created.</li><li>After all attempts fail, the source media will be deleted if either:<ul><li>This setting has not been defined, or</li><li>This setting is set to `none`.</li></ul></li></ul>**Syntax**: `fail_directory = none`                                                                                                                                                   | `fail_directory = ~/media/failure`                      |
| fail\_emails        | **Notifications**<br />Comma-separated emails to notify when a file is unsuccessfully processed. Requires `mail_host`.                                                                                                                                                                                                                                                                                                                                                                                                                                  | `fail_emails = ops@company.org`                         |
| fail\_url           | **Notifications**<br />URL to which an HTTP `POST` is submitted when a file is unsuccessfully processed. [Learn more](#http-notifications).                                                                                                                                                                                                                                                                                                                                                                                                             | `fail_url = http://myserver.net/myservice2?status=fail` |
| halt\_on\_error     | **Source Media Processing**<br />Determines whether processing stops when an issue occurs. Only valid in the main configuration file.<br /><br />**Valid values are**:<ul><li>**1 \| true**: Stop when a job fails due to a source media or configuration issue.</li><li>**0 \| false**: Always continue to the next job.</li></ul>**Default value**: 0                                                                                                                                                                                                 | `halt_on_error = 1`                                     |
| helper\_noext       | **Directory Monitoring**<br />Determines whether supporting files must exclude the source media's file extension.<br /><br />**Valid values are**:<ul><li>**1 \| true**: Supporting file name excludes the source media's extension.</li><li>**0 \| false**: Supporting file name includes the source media's extension.</li></ul>**Example** (when `1 \| true`):<ul><li>Source: `marketing.mp4`</li><li>Config: `marketing.cfg`</li></ul>**Example** (when `0 \| false`):<ul><li>Source: `marketing.mp4`</li><li>Config: `marketing.mp4.cfg`</li></ul> | `helper_noext = 1`                                      |
| ignore              | **Configuration File**<br />Determines whether a directory will be monitored for new files. Define only under a directory-specific section in the main configuration file.<br /><br />**Valid values are**:<ul><li>**1 \| true**: Do not monitor this directory.</li><li>**0 \| false**: Monitor this directory.</li></ul>                                                                                                                                                                                                                              | `ignore = 1`                                            |
| ignoreName          | **Directory Monitoring**<br />Ignore files in a monitored directory with the specified file name(s).<br /><br />**Key information**:<ul><li>File names are case-insensitive.</li><li>Specify multiple files with commas.</li></ul>                                                                                                                                                                                                                                                                                                                      | `ignoreName = thumbs.db,.DS_Store`                      |
| ignoreSuffix        | **Directory Monitoring**<br />Ignore files in a monitored directory with the specified file extension(s).<br /><br />**Key information**:<ul><li>Extensions are case-insensitive.</li><li>Specify multiple extensions with commas.</li></ul>                                                                                                                                                                                                                                                                                                            | `ignoreSuffix = db,txt,jpg`                             |
| mail\_from          | **Notifications**<br />Sender email address for notifications.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `mail_from = automation@company.org`                    |
| mail\_host          | **Notifications**<br />Hostname for the mail server used to send notifications. A port may be appended.<ul><li>**25**: Standard email</li><li>**587**: Secure email</li></ul>If the server requires auth, define `mail_username` and `mail_password`.<br /><br />**Syntax**: `mail_host = Hostname:Port`                                                                                                                                                                                                                                                | `mail_host = smtp.company.com:587`                      |
| mail\_password      | **Notifications**<br />Password for the user defined by `mail_username`. Required only if the mail server requires auth.                                                                                                                                                                                                                                                                                                                                                                                                                                | `mail_password = G183hIU39331f`                         |
| mail\_username      | **Notifications**<br />User account on the mail server used to send notifications. Required only if the mail server requires auth.                                                                                                                                                                                                                                                                                                                                                                                                                      | `mail_username = robo-emails@example.com`               |
| max\_slices         | **Slicing**<br />Limits the number of temporal slices generated from the source media.<br /><br />**Key information**:<ul><li>By default, the entire file is sliced (no limit).</li><li>Useful for troubleshooting or slicing short segments.</li><li>This is an approximate limit; the Slicer may produce a few additional slices.</li></ul>                                                                                                                                                                                                           | `max_slices = 20`                                       |
| multibot            | **Directory Monitoring**<br />Indicates whether multiple Slicebot instances monitor the same directory.<br /><br />**Valid values are**:<ul><li>**0**: Only a single instance monitors any given directory.</li><li>**1**: More than one instance monitors the directory.</li></ul>All Slicebot instances consuming from the same folder must enable multibot mode. Each instance should run on a separate computer.<br /><br />**Default value**: 1                                                                                                    | `multibot = 1`                                          |
| notify\_retries     | **Notifications**<br />Maximum attempts to send an HTTP notification before proceeding to the next file. Applies to `start_url`, `done_url`, and `fail_url`.<br /><br />**Default value**: 3                                                                                                                                                                                                                                                                                                                                                            | `notify_retries = 10`                                   |
| notify\_retry\_wait | **Notifications**<br />Seconds to wait after a failed notification before retrying.<br /><br />**Default value**: 10                                                                                                                                                                                                                                                                                                                                                                                                                                    | `notify_retry_wait = 30`                                |
| require\_captions   | **Processing Prerequisite**<br />Determines whether a closed captioning file is required. [Learn more](#closed-captions).<br /><br />**Valid values are**:<ul><li>**1 \| true**: Do not process unless corresponding captions are found.</li><li>**0 \| false**: Process regardless of captions.</li></ul>                                                                                                                                                                                                                                              | `require_captions = 1`                                  |
| require\_config     | **Processing Prerequisite**<br />Determines whether a file-specific configuration file is required. (Invalid inside file-specific configuration files.)<br /><br />**Valid values are**:<ul><li>**1 \| true**: Require a corresponding file-specific configuration file.</li><li>**0 \| false**: Process regardless of a file-specific configuration file.</li></ul>                                                                                                                                                                                    | `require_config = 1`                                    |
| start\_url          | URL to which an HTTP `POST` request is submitted whenever slicing is initiated. [Learn more](#http-notifications).                                                                                                                                                                                                                                                                                                                                                                                                                                      | `start_url = http://myserver.net/myservice`             |

### Shared Slicer Settings

The following settings are shared with the standalone VOD Slicer.

| Setting                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Example                                                                                                                                                                            |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| apikey **(Required)**   | **Authorization**<br />Sets the secret API key through which Slicebot authenticates to the CMS.<br /><br />**Note**: Bypass this requirement by setting the `SLICER_USER` and `SLICER_APIKEY` environment variables.<br /><br />This API key should correspond to the user defined by the `username` setting.<br /><br />Find API keys via **Settings > Integration Keys > API Keys** on the [Integration Keys](https://cms.uplynk.com/static/cms2/index.html#/settings/integration-keys) page.<br /><br />**Syntax**: `apikey = APIKey`                                                                                                                                                                                                                                                                                                                                                                  | `apikey = abcdefg...`                                                                                                                                                              |
| autoexpire              | **Asset Retention (Library)**<br />Marks an asset for deletion once the specified number of hours have elapsed.<br /><br />The sample configuration will delete assets 48 hours after they have been encoded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `autoexpire = 48`                                                                                                                                                                  |
| breaks                  | **Breaks (Asset)**<br />Inserts ad breaks or boundary breaks at specified time ranges.<br /><br />**Syntax**: `-break <start>[-<stop>][,...]`<ul><li>Times are in decimal seconds</li><li>Multiple breaks separated by commas</li><li>Unlabeled breaks are ad breaks (original content removed)</li><li>Labeled breaks (`label:<start>-<stop>`) are boundary breaks (content preserved)</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `breaks=10.1-30.58,105-151.332` - Two ad breaks with content removed.<br />`breaks=ad1:10.1-20,30.3-40,promo:60-70` - Two boundary breaks (ad1, promo) and one ad break (30.3-40). |
| bug                     | **Asset**<br />Overlays an image on the video at the specified start time for the given duration.<br /><br />**Key information**:<ul><li>Only RGBA PNG images may be overlaid onto video.</li><li>The overlay respects the PNG's transparency.</li><li>The PNG image should match the source video's resolution.</li><li>Start time and duration are specified in milliseconds.</li><li>Use a negative start time to count from the end of the asset (e.g., `-5000` starts 5 seconds before the end).</li><li>Specify multiple overlays by using three commas as a delimiter.</li><li>If multiple images overlap, Z-order is determined by their listed order (later entries are on top).</li></ul>**Syntax**: `bug = PNGFile,StartTime,Duration`<br /><br />The sample adds `overlay1.png` at the start for 5s and `overlay2.png` five seconds before the end; overlapping favors `overlay2.png` on top. | `bug = overlay1.png,0,5000,,,overlay2.png,-5000,5000`                                                                                                                              |
| description             | **Asset (Library)**<br />Assigns a name to the asset generated from the source media. Typically used in file-specific configurations. By default, assets are named after the source media's file name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `description = Marketing Event 2016`                                                                                                                                               |
| enc\_wait               | **Slicebot**<br />Determines whether Slicebot waits for cloud encoding to finish before processing the next file.<br /><br />**Valid values are**:<ul><li>**1**: Wait until encoding completes.</li><li>**0**: Move on after slicing completes.</li></ul>**Default value**: 0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `enc_wait = 1`                                                                                                                                                                     |
| external\_id            | **Asset (Library)**<br />Assigns an external ID to the generated asset. By default, duplicate external IDs are allowed. Prefix an ID with `_replace:` to replace existing assets with the same ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `external_id = ep20115e_12`<br />`external_id = _replace:ep20115e_12`                                                                                                              |
| fade                    | **Asset**<br />Fades audio and/or video in/out from the specified start time.<br /><br />**Key information**:<ul><li>**Method**: `in` or `out`</li><li>**MediaType**: `audio`, `video`, or `both`</li><li>Start time and duration are in milliseconds.</li><li>Negative start times are from the end (e.g., `-5000`).</li><li>Specify multiple fades using three commas as a delimiter.</li></ul>**Syntax**: `fade = Method,MediaType,StartTime,Duration`                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `fade = in,both,0,5000,,,out,both,-5000,5000`                                                                                                                                      |
| force\_aspect\_ratio    | **Asset**<br />Forces the video to the specified aspect ratio. Use this to ingest vertical videos. <br /><br />**Syntax**: `force_aspect_ratio = WidthRatio:HeightRatio`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `force_aspect_ratio = 16:9`                                                                                                                                                        |
| libraries               | **Asset (Library)**<br />Adds an asset to one or more shared libraries.<br /><br />**Key information**:<ul><li>A library may be specified by name or GUID.</li><li>Library names must be an exact, case-sensitive match.</li><li>Add multiple libraries using commas.</li></ul>**Add by name**: `libraries = LibraryName`<br />**Add by GUID**: `libraries = LibraryGUID`<br />**Add multiple**: `libraries = Library1,Library2,LibraryN`                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `libraries = 357...,8b0...`                                                                                                                                                        |
| meta                    | **Asset (Library)**<br />Adds metadata to the asset.<br /><br />**Key information**:<ul><li>Field names must be unique; use lowercase letters, digits, and underscores.</li><li>Enclose values containing spaces in quotes.</li><li>Assign multiple fields using three commas as a delimiter.</li></ul>**Syntax**: `meta = Field=Value`<br /><br />Alternatively, assign metadata via a JSON file. [Learn more](#metadata-files).                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `meta = rating=TV-13`<br />`meta = rating=TV-13,,,air_date=20160105`                                                                                                               |
| meta\_int               | **Asset (Library)**<br />Adds integer metadata to the asset.<br /><br />**Key information**:<ul><li>Field names must be unique (case-insensitive).</li><li>Non-integer values are coerced to `0`.</li><li>Assign multiple fields using three commas as a delimiter.</li></ul>**Syntax**: `meta_int = Field=Integer`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `meta_int = is_ad=1`<br />`meta_int = is_ad=1,,,year=2013`                                                                                                                         |
| mix\_atracks            | **Asset**<br />Mixes multiple audio tracks into a single track (e.g., when left/right are on separate tracks).<br /><br />**Key information**:<ul><li>Track index is zero-based (`0` is the first audio track).</li><li>Channels: `L`, `R`, `C`, `RL`, `RR`, `SL`, `SR`, `LFE`.</li><li>Use commas between track mappings.</li></ul>**Syntax**: `mix_atracks = Track1=Channel1,Track2=Channel2,...`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `mix_atracks = 0=L,1=R,2=C,3=RL,4=RR,5=LFE`                                                                                                                                        |
| poster                  | **Asset**<br />Generates a poster image from the frame at the specified time. Must be used with `poster_size`. Ignored when `poster_file` is defined.<br /><br />**Syntax**: `poster = Time`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `poster = 5000`                                                                                                                                                                    |
| poster\_file            | **Asset**<br />Sets the asset's poster image to the specified file.<br /><br />**Syntax**: `poster_file = FullPath`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `poster_file = /images/poster.png`                                                                                                                                                 |
| poster\_size            | **Asset**<br />Sets the size of the poster image.<br /><br />**Key information**:<ul><li>Must be used with the *poster* time parameter.</li><li>Ignored when `poster_file` is defined.</li><li>If neither *poster* nor `poster_file` is defined, a thumbnail of on-demand content is used.</li><li>No upscaling beyond source resolution.</li><li>Poster images are scaled down preserving aspect ratio.</li></ul>**Syntax**: `poster_size = WidthxHeight`                                                                                                                                                                                                                                                                                                                                                                                                                                                | `poster_size = 512x512`                                                                                                                                                            |
| skip\_drm               | **Asset**<br />Determines whether the asset's playback URLs must be signed.<br /><br />**Valid values are**:<ul><li>**1**: Encrypt the asset but allow unsigned playback URLs (useful for ads that require independent playback).</li><li>**0**: Playback requires a signed playback URL.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `skip_drm = 1`                                                                                                                                                                     |
| thumbnails              | **Asset**<br />Adds one or more thumbnails.<br /><br />**Key information**:<ul><li>A default thumbnail is created even if not specified.</li><li>The file name for each thumbnail is prefixed as specified.</li><li>Each thumbnail is bounded by the specified width and height, preserving aspect ratio.</li><li>Additional thumbnails may add cost and impact processing speed.</li><li>Add multiple thumbnails using commas.</li></ul>**Syntax**: `thumbnails = Prefix:WidthxHeight,Prefix2:Width2xHeight2,...`                                                                                                                                                                                                                                                                                                                                                                                        | `thumbnails = tiny:50x50,med:400x400`                                                                                                                                              |
| timedmeta               | **Asset**<br />Adds timed metadata at the specified time.<br /><br />**Single Field Syntax**: `timedmeta = Time:Field=Value`<br />**Multiple Fields Syntax**: `timedmeta = Time1:Field1=Value1,Time2:Field2=Value2,...`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `timedmeta = 0:TIT2=MyTitle,2000:TCOM=Myself`                                                                                                                                      |
| trim                    | **Asset**<br />Trims content prior to the specified start time; optionally trims by duration.<br /><br />Specify *StartTime* and *Duration* in milliseconds. Some file types may affect frame accuracy by a few milliseconds.<br /><br />**Start only**: `trim = StartTime`<br />**Start and duration**: `trim = StartTime,Duration`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `trim = 3000,52500`                                                                                                                                                                |
| username **(Required)** | **Authorization**<br />Identifier used for authentication for the account to which the asset will be uploaded. You may specify either a workspace ID (formerly known as owner ID) or a user name (typically the email address associated with your account). Using a workspace ID is recommended because it is immutable, whereas user names and email addresses may change over time. You can bypass by setting `SLICER_USER` and `SLICER_APIKEY` environment variables.                                                                                                                                                                                                                                                                                                                                                                                                                                 | `username = a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6`<br /> `username = joe@example.com`                                                                                                   |

<br />

### Closed Captions

You can provide Slicebot with closed caption data by placing a TTML file in the same directory as the media file. TTML files are simple text files that you can create with third-party tools or any text editor:

```xml
<?xml version="1.0" encoding="utf-8"?>
<tt xml:lang="en" xmlns="http://www.w3.org/2006/04/ttaf1" xmlns:tts="http://www.w3.org/2006/04/ttaf1#styling">
  <head>
    <styling>
      <style id="defaultSpeaker" tts:fontSize="24" tts:fontFamily="Arial" tts:fontWeight="normal" tts:fontStyle="normal" tts:textDecoration="none" tts:color="white" tts:backgroundColor="black" tts:textAlign="center" />
      <style id="defaultCaption" tts:fontSize="24" tts:fontFamily="Arial" tts:fontWeight="normal" tts:fontStyle="normal" tts:textDecoration="none" tts:color="white" tts:backgroundColor="black" tts:textAlign="center" />
    </styling>
  </head>
  <body style="defaultCaption" id="thebody">
    <div xml:lang="en">
      <p begin="00:00:01.420" end="00:00:02.620"><metadata ccrow="14" cccol="3" /><span tts:fontStyle="italic">THIS IS SOME TEXT...</span></p>
      <p begin="00:00:06.620" end="00:00:09.790"><metadata ccrow="13" cccol="1" />(Doorbell rings)</p>
      <p begin="00:00:11.100" end="00:00:13.000"><metadata ccrow="14" cccol="8" />♪ LA LA LA SINGING ♪</p>
      <p begin="00:00:20.460" end="00:00:22.170"><metadata ccrow="14" cccol="0" />THIS IS MORE TEXT</p>
    </div>
  </body>
</tt>
```

The `require_captions` config setting ensures that Slicebot skips a file if it does not have a corresponding TTML file. As with other settings, you can use it in the global, directory, or per-file context.

TTML files use a naming convention similar to config files: take the name of the associated media file and add a ".ttml" extension. For example, if Slicebot is processing a file named /tmp/foo/film.mp4, it looks for a file named /tmp/foo/film.mp4.ttml and, if found, uses it as the source of closed caption data. If no corresponding TTML file exists, the video will not have any closed caption data. Note that the helper\_noext setting can alter the naming convention for TTML files.

<Callout icon="📘" theme="info">Only hh:mm:ss.sss time formats are currently supported in the TTML file.</Callout>

### Metadata Files

You can assign metadata key-value pairs to an asset using individual settings. For larger amounts of metadata, however, it may be more convenient to use a metadata file. This file is a JSON text file containing the metadata you want associated with the media file. As with caption and config files, the name of the metadata file is the media filename with an additional extension: .meta.json. For example, if a media file is named video123.mp4, the associated metadata file would be named video123.mp4.meta.json.

The contents of the metadata file must be a valid JSON object, or processing the file will produce an error. Structured metadata is supported, although it is not currently fully displayed or editable in the CMS UI.

```json
{
    "genre" : "comedy",
    "network" : "ZNN",
    "season" : 1,
    "episode" : 13
}
```

In general, a given media file will use individual metadata settings or a metadata file, but not both. However, if both are specified for a particular file, metadata from the file is applied first, followed by any metadata settings.

## HTTP Notifications

HTTP notifications provide an additional way to integrate a system with your content production workflow. Slicebot can submit an HTTP POST request whenever one of the following events occurs:

* Slicing Starts (start\_url)
* Slicing Completes (done\_url)
* Slicing Error (fail\_url)

Enable HTTP notifications by setting one or more of the above settings to the URL that will be requested.

Email notifications may also be sent whenever slicing completes (done\_emails) or when an error occurs (fail\_emails).

### HTTP POST Request

Slicebot submits an HTTP POST request using the default Internet media type (i.e., [application/x-www-form-urlencoded](https://www.w3.org/TR/html4/interact/forms.html#h-17.13.4.1)). The body of this request consists of a single line with the following parameters:

| Parameter    | Description                                                                                                                         |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| filename     | Indicates the full path and the filename of the file.                                                                               |
| asset\_id    | Indicates the system-generated unique ID of the new asset.                                                                          |
| external\_id | Indicates the external ID defined in the configuration. If one has not been defined, then it will be set to an empty string.        |
| description  | Indicates the file's description defined in the configuration. If one has not been defined, then it will be set to an empty string. |
| status       | Indicates the result of the slicing operation. Valid values are either "ok" or "error."                                             |

In addition to the above parameters, any custom query string parameters defined in the configuration setting (i.e., start\_url, done\_url, and fail\_url) are automatically stripped from the request and inserted into the request body. This allows custom parameters to be passed to the remote server as needed.

[View a sample scenario](#sample-http-notification-scenario).

<Callout icon="📘" theme="info">Custom query string parameters whose names match one of the above system-defined parameters (e.g., filename or description) will be ignored.</Callout>

<Callout icon="📘" theme="info">To allow for future expansion, the server process that receives the HTTP POST should silently ignore unrecognized parameters.</Callout>

#### Notification Issues

Slicebot logs an error under the following conditions:

* It has been configured to request an invalid URL.
* A valid URL has been provided, but the server is unreachable.
* A valid URL has been provided, but it generates a non-200 response.

After logging the error, Slicebot reattempts the HTTP notification several times as determined by the notify\_retries setting. After each attempt, it pauses for a few seconds as determined by the notify\_retry\_wait setting. If it is unable to successfully submit the HTTP POST request, it moves on to the next file.

#### Sample HTTP Notification Scenario

This sample scenario assumes that the done\_url setting is configured to:

`http://www.example.com/slicing/handler?custom=1234&other=5678`

The following sample HTTP POST request is submitted once a file called "video.m4v" has been successfully sliced.

```http
POST /slicing/handler HTTP/1.1
Host: www.example.com
Accept-Encoding: identity
Content-Length: 161
Content-Type: application/x-www-form-urlencoded
Connection: close
User-Agent: upLynk-slicebot/1.0
status=ok&other=5678&description=The%20file&filename=%2Fopt%2Ft%2Fmyvideos%2Fvideo.m4v&external_id=dummy_id&custom=1234&asset_id=a9119d7afc5242319d028794ae283ea7
```

Notice that the custom query string parameters (i.e., custom and other) defined in the done\_url setting were automatically stripped from the request and inserted into the request body.