cURL
PHP
Java
Node.JS
C#

Preset Jobs Output Naming

By default Preset Job output filename is generated in a form of uuid value. E.g. for mp4 default output file name is specified as

{uuid}.mp4

in your Transcoding Profile video settings output path. Here {uuid} is a placeholder and will be substituted with an actual value generated while job is executed.

For Preset Jobs having output in adaptive streaming formats (HLS and MPEG-DASH) it's by default saved in a folder named {uuid}.

You can set your own naming conventions using special param for /v1/start_encode method named output_path_variables.

To do this you need to define your variables (placeholders) in your Transcoding Profile Output Path. For instance you want to save each video in a folder with video category name and pass your internal video ID as a video filename. Open Transcoding Profile UI, then edit Output Path in Video Settings:

Output Path Variables

For HLS and MPEG-DASH outputs you need to specify a single Output Path for all resolutions:

Output Path Variables For Adaptive Streaming

When calling /v1/start_encode method, specify the following JSON as a value for output_path_variables param:

{
    "category": "concert_videos",
    "video_id": "12345"
}

As a result system will save your video to the following destination path in your S3 bucket or FTP folder (depending on the Transfer Method type):

videos/concert_videos/1080/12345.mp4

Please note: Output Path settings are only applied when you specify Transfer Method for a job. System uses default naming conventions in case the output is saved to Qencode temporal storage.

Specifying output path variables

Using cURL:

curl https://api.qencode.com/v1/start_encode \
        -d task_token=63adfb01d408081b10440682f3a64 \
        -d uri="https://your-server.com/video.mp4" \
        -d profiles=5a2a846a26e88 \
        -d transfer_method=5aa2875489681 \
        -d output_path_variables='{"category":"concert_videos","video_id":"12345"}'

Using Qencode PHP SDK:

$video_url = 'https://your-server.com/video.mp4';
//replace with your profile ID 
$transcodingProfileId = '5a2a846a26e88'; 
//replace with your transfer method ID
$transferMethodId = '5aa2875489681';

//setting Output path variables
$task->output_path_variables->category = 'concert_videos';
$task->output_path_variables->video_id = '12345';

$task->start($transcodingProfileId, $video_url, $transferMethodId, $payload);

Using Qencode Node.JS SDK:

const videoUrl = "https://your-server.com/video.mp4";
//replace with your profile IDs 
const transcodingProfiles = ["5a2a846a26e88", "5a2a846a28604"]; 
//replace with your transfer method ID
const transferMethod = "5aa2875489681";

//setting Output path variables
const outputPathVariables = null;

task.Start(transcodingProfiles, videoUrl, transferMethod, payload, outputPathVariables);

Using Qencode Java SDK:

String videoUrl = "https://your-server.com/video.mp4";
//replace with your profile IDs 
String[] transcodingProfiles = new String[] { "5a2a846a26e88", "5a2a846a28604" };
//replace with your transfer method ID
String transferMethod = "5aa2875489681";

//setting Output path variables
HashMap vars = new HashMap();
vars.put("category", "concert_videos");
vars.put("video_id", "12345");

TranscodingTask task = client.CreateTask();
task.setUri(videoUrl);
task.setTranscodingProfiles(String.join(",", transcodingProfiles);
task.setOutputPathVariables(vars);
task.Start();

Using Qencode C# SDK:

var videoUrl = "https://your-server.com/video.mp4";
//replace with your profile IDs 
var transcodingProfiles = new string[] { "5a2a846a26e88", "5a2a846a28604" };
//replace with your transfer method ID
var transferMethod = "5aa2875489681";

var started = task.Start(transcodingProfiles, videoUrl, transferMethod, payload);
Console.WriteLine("Status URL: " + started.status_url);

Stitching Videos

Stitching is a process of combining two or more video files together in a single output.
In order to do stitching with a Preset Job (the one that's launched with /v1/start_encode method), specify stitch param instead of uri.

If you want to stitch videos within a Custom Job (launched with /v1/start_encode2 method) use stitch attribute of query object instead of source attribute.

Stitch should be a JSON list of strings containing video URLs or video-objects having the following structure:

Video object description

ATTRIBUTES

url

required

Video URL.
Note: you can specify same video URL in different video-objects in order to stitch clips from the same video.

start_time

optional

Specifies the time (in seconds) from where to begin transcoding your input file. Used for video clips.

duration

optional

Specifies how much of the video to transcode (in seconds) after start_time. Used for video clips.

See the example of a stitch value below (the syntax is the same both for Preset and Custom jobs):

[
 "https://your-server.com/video1.mp4", 
 "https://your-server.com/video2.mkv",
 {
    "url":"https://your-server.com/video3.mp4", 
    "start_time":"100.0", 
    "duration":"60.0"
 }
]

If you are developing with the help of the SDKs we provide in different programming languages, add videos to stitch job as instances of StitchVideoItem class. See examples for the language of your choice on the right pane.

It's recommended to explicitly specify bitrate (or quality), framerate and keyframe interval params for stitch jobs. Input videos can have different settings making it hard to predict what values for these params output video will have. For instance if input videos have different framerate and it's not specified explicitly in Transcoding Profile or Custom job settings, framerate of the first video in a batch will be used for output video.

Launching a stitch job

Using cURL:

curl https://api.qencode.com/v1/start_encode \
        -d task_token=63adfb01d408081b10440682f3a64 \
        -d stitch='["https://your-server.com/video1.mp4", "https://your-server.com/video2.mkv"]' \
        -d profiles=5a2a846a26e88

Preset job (using Transcoding Profile):

QencodeApiClient client = new QencodeApiClient(API_KEY);
TranscodingTask task = client.CreateTask();
StitchVideoItem part1 = task.addStitchVideoItem(VIDEO_URL);
part1.setStartTime(60);
part1.setDuration(10);
task.addStitchVideoItem(VIDEO_URL2);
task.setTranscodingProfiles(TRANSCODING_PROFILE_ID);
task.setTransferMethod(TRANSFER_METHOD_ID);
task.start();

Custom job:

QencodeApiClient client = new QencodeApiClient(API_KEY);
TranscodingTask task = client.CreateTask();

StitchVideoItem part1 = task.addStitchVideoItem(VIDEO_URL);
part1.setStartTime(60);
part1.setDuration(10);
task.addStitchVideoItem(VIDEO_URL2);

CustomTranscodingParams transcodingParams = new CustomTranscodingParams();transcodingParams.setSource(TEST_VIDEO_URL);
Destination destination = new Destination();
Format format = new Format();
destination.setUrl(S3_PATH);
destination.setKey(S3_KEY);
destination.setSecret(S3_SECRET);
format.setDestination(destination);
format.setOutput("advanced_hls");

Stream stream = new Stream();
stream.setSize("1920x1080");
stream.setFramerate(29.97);
stream.setKeyframe(25);
stream.setBitrate(4800);
stream.setAudioBitrate(128);
format.getStream().add(stream);
transcodingParams.getFormat().add(format);

task.startCustom(transcodingParams);

Adding Subtitles

You can create a closed captions from existing subtitles in text format.
For Preset Jobs specify a subtitles param as a JSON-encoded list of subtitle objects.
For Custom Jobs, use subtitles attribute of a format object.
Currently supported subtitles formats are: SRT, ASS.

Subtitle object description

ATTRIBUTES

source

required

Subtitles file URL

language

required

Subtitles file language

See the example of a subtitles value below (the syntax is the same both for Preset and Custom jobs):

[
   {
     "source" : "https://server.com/sub/video.ENG.srt",
     "language" : "eng"
   },
   {
     "source" : "https://server.com/sub/video.FRA.srt",
     "language" : "fra"
   }
]

Request Examples

Launching a Preset Job with subtitles:

curl https://api.qencode.com/v1/start_encode \
        -d task_token=63adfb01d408081b10440682f3a64 \
        -d uri="https://your-server.com/video.mp4" \
        -d profiles=5a2a846a26e88 \
        -d transfer_method=5aa2875489681 \
        -d subtitles='
        [
         {
           "source" : "https://server.com/en.srt",
           "language" : "eng"
         },
         {
           "source" : "https://server.com/fr.srt",
           "language" : "fra"
         }
        ]'

Launching a Preset Job with subtitles:

$video_url = 'https://your-server.com/video.mp4';
//replace with your profile IDs 
$transcodingProfiles = array('5a2a846a26e88'); 
//replace with your transfer method ID
$transferMethodId = '5aa2875489681';

$task->addSubtitles('https://server.com/en.srt', 'eng');
$task->addSubtitles('https://server.com/fr.srt', 'fra');

$task->start($transcodingProfiles, $video_url, $transferMethodId);

Launching a Preset Job with subtitles:

const videoUrl = "https://your-server.com/video.mp4";
//replace with your profile IDs 
const transcodingProfiles = ["5a2a846a26e88"]; 
//replace with your transfer method ID
const transferMethod = "5aa2875489681";

task.addSubtitles("https://server.com/en.srt", "eng");
task.addSubtitles("https://server.com/fr.srt", "fra");

task.Start(transcodingProfiles, videoUrl, transferMethod);

Launching a Preset Job with subtitles:

String videoUrl = "https://your-server.com/video.mp4";
//replace with your profile IDs 
String[] transcodingProfiles = new String[] { "5a2a846a26e88" };
//replace with your transfer method ID
String transferMethod = "5aa2875489681";

TranscodingTask task = client.CreateTask();
task.setUri(videoUrl);
task.setTranscodingProfiles(String.join(",", transcodingProfiles);

task.addSubtitles("https://server.com/en.srt", "eng");
task.addSubtitles("https://server.com/fr.srt", "fra");

task.Start();

Launching a Preset Job with subtitles:

var videoUrl = "https://your-server.com/video.mp4";
//replace with your profile IDs 
var transcodingProfiles = new string[] { "5a2a846a26e88" };
//replace with your transfer method ID
var transferMethod = "5aa2875489681";

task.addSubtitles("https://server.com/en.srt", "eng");
task.addSubtitles("https://server.com/fr.srt", "fra");

var started = task.Start(transcodingProfiles, videoUrl, transferMethod);
Console.WriteLine("Status URL: " + started.status_url);

Response Example

{
 "error": 0, 
 "status_url": "https://api.qencode.com/v1/status" 
}

Adding Watermark

Adding Watermark with Preset Jobs

Open your Transcoding profile settings and for each Video setting enable Watermark section and specify needed properties:

Thumbnails Settings

Adding Watermark with Custom Jobs

Specify watermark properties by adding a logo attribute to format object. See example of a logo object below:

{
 "source": "https://your-server.com/watermark.png",
 "x": 10,
 "y": 10
}

You should specify public url to an image in logo.source attribute.

In case you are creating output in adaptive streaming format like HLS or MPEG-DASH, please make logo attribute of a stream object.

See Starting a Custom Job section for detailed specification of format object attributes.

Request Examples

Launching a Custom Job with watermark:

curl https://api.qencode.com/v1/start_encode2 \
     -d task_token=b49e034d198262f1d5d15ed9f3cb8 \
     -d query='{"query": {
     "source": "https://your-server.com/video.mp4",
     "format": [
       {
         "output": "mp4",
         "destination": {
           "url":"s3://s3-us-east-1.amazonaws.com/yourbucket/output.mp4",
           "key":"abcde12345",
           "secret":"abcde12345",
           "permissions": "public-read"
         },
         "framerate": "29.97",
         "keyframe": "25",
         "size": "360x240",
         "logo": {
           "source": "https://your-server.com/watermark.png",
           "x": 10,
           "y": 10
         }
       }
     ]
   }
 }'

Response Example

{
 "error": 0, 
 "status_url": "https://api.qencode.com/v1/status" 
}

Creating Thumbnails

There are two types of thumbnails you can create:

  • Individual thumbnails

Use this method to create one or several thumbnails per video. For individual thumbnails you should specify thumbnail time (a moment in video - % of video duration) and thumbnail size (width and height in pixels) along with output path.

For example, you specified three time settings at
- 0% (beginning of the video),
- 50% (middle of the video),
- 100% (end of the video)
and two sizes of 640x360px and 360x240px.
This results in generating two thumbnails of specified sizes in each of three moments specified. So 6 thumbnails in total is created.

  • Interval-based thumbnails

This type of thumbnails is useful if you need to create many thumbnails per video or you need exact time intervals between thumbnails.
To create interval-based thumbnails you need to specify interval in seconds between thumbnails and thumbnails size (width and height in pixels).
All thumbnails of a specific size are saved into a folder along with a file in VTT format containing information about the timestamp of each image.

Creating Thumbnails with Preset Jobs

Open your Transcoding profile settings and specify time (in % of video duration) and size settings for thumbnails.

Thumbnails Settings

Currently you can only create individual thumbnails with Preset Jobs.

Creating Thumbnails with Custom Jobs

To create individual thumbnails set output attribute of a format object to thumbnail. Example of a format object for individual thumbnail taken in the middle of a video is listed below:

{
 "output": "thumbnail",
 "time": "0.50",
 "width": "320",
 "height": "240",
 "destination": {
   "url":"s3://s3.amazonaws.com/bucket/thumb/50_320x240.png",
   "key":"your_access_key",
   "secret":"your_secret_key",
   "permissions": "public-read"
 },
 "user_tag": "50_320x240"
}

You should specify full path to an image in destination.url attribute.

To create interval-based thumbnails set output attribute of a format object to thumbnails. Example of a format object for interval-based thumbnails generated each 30 seconds of a video is listed below:

{
  "output" : "thumbnails",
  "destination": {
    "url":"s3://s3.amazonaws.com/bucket/thumb/",
    "key":"your_access_key",
    "secret":"your_secret_key",
    "permissions": "public-read"
  },
  "interval": 30,
  "width" : 320,
  "height" : 240
}

You should specify path to a folder where images with .vtt file will be saved in destination.url attribute.

See Starting a Custom Job section for detailed specification of format object attributes.