Colossyan API Documentation
Tracks
Tracks
Tracks are the building blocks of scenes. You define the content of the video in tracks.
There are different types of tracks, for different purposes. To differentiate between them we use the type property.
Image track
An image track is nothing more than an image embedded in a scene. It has the following properties:
| Key | Default | Required | Type | Description |
|---|---|---|---|---|
| type | - | Yes | string | For an image track it has to be set to image |
| size | - | Yes | { height: number, width: number } | The size of the visible track in pixels |
| position | - | Yes | { x: number, y: number } | The position of the visible track in pixels starting from the top left |
| imageUrl | - | Yes | string | The url of the image |
| startTimeGap | - | No | number | How much after the beginning of the scene the track should start in milliseconds |
| endTimeGap | - | No | number | How much before the end of the scene the track should end in milliseconds |
| duration | - | No | number | How long the track should be in milliseconds |
| referenceId | - | No | string | A user given reference for the track |
| sequentialBlendId | - | No | string | Tracks in sequential scenes with the same sequentialBlendId are seamlessly concatenated. |
Video track
A video track consists of a single video clip embedded in a scene. It has the following properties:
| Key | Default | Required | Type | Description |
|---|---|---|---|---|
| type | - | Yes | string | For an image track it has to be set to video |
| size | - | Yes | { height: number, width: number } | The size of the visible track in pixels |
| position | - | Yes | { x: number, y: number } | The position of the visible track in pixels starting from the top left |
| videoUrl | - | Yes | string | The url of the video |
| removeBackground | false | No | boolean | Whether to remove the background of the video or not |
| startTimeGap | - | No | number | How much after the beginning of the scene the track should start in milliseconds |
| endTimeGap | - | No | number | How much before the end of the scene the track should end in milliseconds |
| duration | - | No | number | How long the track should be in milliseconds |
| referenceId | - | No | string | A user given reference for the track |
| sequentialBlendId | - | No | string | Tracks in sequential scenes with the same sequentialBlendId are seamlessly concatenated. |
Actor track
An actor track defines a video with a lipsynched speaker on it. You can either upload your own audio, or you can define your audio with our built-in text-to-speech service.
| Key | Default | Required | Type | Description |
|---|---|---|---|---|
| type | - | Yes | string | For an image track it has to be set to actor |
| size | - | No | { height: number, width: number } | The size of the visible track in pixels. It's required when the actor is defined. |
| position | - | No | { x: number, y: number } | The position of the visible track in pixels starting from the top left. It's required when the actor is defined. |
| actor | - | No | string | The name of the actor we want in our track. If we set the actor we must provide the size and positon properties too. Click here to see a list of actors. |
| removeBackground | false | No | boolean | Whether to remove the background of the video or not |
| startTimeGap | - | No | number | How much after the beginning of the scene the track should start in milliseconds |
| endTimeGap | - | No | number | How much before the end of the scene the track should end in milliseconds |
| duration | - | No | number | How long the track should be in milliseconds |
| referenceId | - | No | string | A user given reference for the track |
| sequentialBlendId | - | No | string | Tracks in sequential scenes with the same sequentialBlendId are seamlessly concatenated. |
| audioUrl | - | No | string | Url of the audio. Only has to be defined when the audio is supplied and not generated by text-to-speech |
| audioType | - | No | 'static' or 'dynamic' | The type of the audio (only has to be specified when the audio is supplied and not generated by text-to-speech). static refers to an audio which doesn't change over multiple videos, where as dynamic means an audio which often changes on a per video bases. |
| speakerId | - | No | string | The id of the speaker in case the speech is generate by text-to-speech. See voices |
| text | - | No | string | The text to say in case of text-to-speech |
| pause | - | No | number | The pause in seconds to have after each sentence in case of text-to-speech, if its supported for the selected speaker. Has to be between 0 and 5, inclusive. |
| pitch | - | No | number | The pitch of the voice in case of text-to-speech, if its supported for the selected speaker. Has to be between 0.5 and 1.5, inclusive. |
| speed | - | No | number | The speech speed in case of text-to-speech, if its supported for the selected speaker. Has to be between 0.5 and 1.5, inclusive. |
The Media object
| Key | Default | Required | Type | Description |
|---|---|---|---|---|
| type | - | Yes | string | The type of the file. Its value has to be video or image appropriately. |
| url | - | Yes | string | The url of the media file |
Text track
A text track can be used to add subtitles and captions to your videos.
| Key | Default | Required | Type | Description |
|---|---|---|---|---|
| type | - | Yes | string | For a text track it has to be set to text |
| size | - | Yes | { height: number, width: number } | The size of the visible track in pixels |
| position | - | Yes | { x: number, y: number } | The position of the visible track in pixels starting from the top left |
| text | - | Yes | string | The text you want to display on the track |
| font | Helvetica | No | string | The font of the text. Click here to see a list of supported fonts |
| fontSize | 20 | No | number | Size of the font in pixels. Can only be an integer. |
| color | #000000 | No | string | Hex code of the text's color |
| backgroundColor | transparent | No | string | Hex code of the text background's color or "transparent" |
| strokeColor | null | No | string | Hex code of the text stroke's color or null for no stroke |
| strokeWidth | 1 | No | number | Width of the stroke of the text in pixels, can be float |
| startTimeGap | - | No | number | How much after the beginning of the scene the track should start in milliseconds |
| endTimeGap | - | No | number | How much before the end of the scene the track should end in milliseconds |
| duration | - | No | number | How long the track should be in milliseconds |
| referenceId | - | No | string | A user given reference for the track |
| sequentialBlendId | - | No | string | Tracks in sequential scenes with the same sequentialBlendId are seamlessly concatenated. |
Audio track
An audio track can be used to add background music or sound effects to your videos.
| Key | Default | Required | Type | Description |
|---|---|---|---|---|
| type | - | Yes | string | For an audio track it has to be set to audio |
| audioUrl | - | Yes | string | The url of the audio |
| volume | 1 | No | number | Volume modifier to apply to the audio. 0.5 is 50% volume, 2 is 2x volume |
| startTimeGap | - | No | number | How much after the beginning of the scene the track should start in milliseconds |
| endTimeGap | - | No | number | How much before the end of the scene the track should end in milliseconds |
| duration | - | No | number | How long the track should be in milliseconds |
| referenceId | - | No | string | A user given reference for the track |
| sequentialBlendId | - | No | string | Tracks in sequential scenes with the same sequentialBlendId are seamlessly concatenated. |