Learn how to stitch multiple video segments into a single continuous output using the RMS API. This guide provides API reference documentation, workflow steps, and troubleshooting guidance for video stitching.
In this article:
Before you begin:
- Authenticate using the RMS API Authentication
- Upload media files (1 or more) to use as segment sources (use RMS Console or your SDK)
Stitching concept
Video stitching combines multiple video segments (subclips) from one or more source assets into a single, continuous output video. Unlike trimming, which extracts a portion from a single source, stitching creates a new timeline by joining video segments together in a set order.
Trimming and stitching are both supported in the RMS API.
Common use cases:
- Combine highlights from multiple source videos.
- Join specific segments from the same source video in a new order.
- Merge intro, main content, and outro from separate assets.
Stitching automatically handles encoding, format conversion, and quality optimization to produce a continuous output video.
Workflow
See the stitching process example, from input assets through subclip definition to the final stitched output.
The parameters and usage are detailed in the Construct a stitching request. Use the following steps to build a stitching job:
1. Prepare the job request
Begin configuring your stitching job request and set up the basic job parameters, including transform and other URL components.
2. Define subclips
The order of subclips in your request determines the final stitching sequence.
- Reference each asset in the input parameters for each source video.
-
Set timing parameters for each source (optional):
- Set start time - when to begin the subclip.
- Set end time - when to end the subclip.
Example from the diagram: Subclip 1 has a start time of PT10SS
and an end time of PT30S
. Subclip 2 has a start time of PT0S
and an end time of PT15S
.
3. Specify the output asset
- Specify the output asset name where your stitched video will be saved.
- The output inherits encoding settings from your selected transform, including the media format.
4. Submit the stitching job
The system automatically:
- Trims sources (if timing is specified).
- Stitches subclips in the specified order.
- Starts encoding using your selected transform.
- Saves the final stitched video to the output asset.
5. Retrieve the final output
Get an output containing a single continuous video. See the Response Body example below.
Construct a stitching request
Use this reference when building your API calls to stitch multiple video clips together.
PUT https://{{api-endpoint}}/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Media/mediaServices/{accountName}/transforms/{transformName}/jobs/{jobName}?api-version={{api-version}}
Request URL structure:
-
api-endpoint
: Placeholder for your RMS API endpoint. -
subscriptionId
: This is your Azure subscription ID, a unique identifier for your Azure subscription. -
resourceGroup
: The name of the resource group where your Media Services account is located. -
accountName
: This is the name of your Media Services account. -
transformName
: Select a transform - the predefined processing settings (resolution, bitrate, etc.). -
jobName
: the job name. -
api-version={{api-version}}
: This specifies the version of the AMS API you used. Any valid version number will work for your requests. Example:api-version=2018-07-01
.
Request Body:
{
"properties": {
"input": {
"@odata.type": "#Microsoft.Media.JobInputSequence",
"inputs": [
{
"@odata.type": "#Microsoft.Media.JobInputAsset",
"AssetName": "your-asset-name",
"start": {
"@odata.type": "#Microsoft.Media.AbsoluteClipTime",
"Time": "PT10S"
},
"end": {
"@odata.type": "#Microsoft.Media.AbsoluteClipTime",
"Time": "PT30S"
}
},
{
"@odata.type": "#Microsoft.Media.JobInputAsset",
"AssetName": "your-asset-name2",
"start": {
"@odata.type": "#Microsoft.Media.AbsoluteClipTime",
"Time": "PT30S"
},
"end": {
"@odata.type": "#Microsoft.Media.AbsoluteClipTime",
"Time": "PT40S"
}
}
]
},
"outputs": [
{
"@odata.type": "#Microsoft.Media.JobOutputAsset",
"assetName": "stitch1-name"
}
],
"priority": "Normal"
}
}
Parameters
Request Body parameters used in the stitching request:
Name | Required | Type | Description |
---|---|---|---|
@odata.type: #Microsoft.Media.JobInputSequence |
True | string | Specifies that this job will stitch multiple video segments together in sequence. |
inputs[] - JobInputs that make up the timeline: |
|||
@odata.type: #Microsoft.Media.JobInputAsset |
True (one of or
must be provided) |
string | Represents an Asset for input into a Job. Specify the asset name in the "AssetName" parameter. |
@odata.type: #Microsoft.Media.JobInputHttp |
string | Represents the HTTPS job input. Specify the URL in the "baseUri" parameter. |
|
Time format: | |||
@odata.type: #Microsoft.Media.AbsoluteClipTime |
string | Use AbsoluteClipTime with ISO 8601 duration format for the Time parameter:
|
|
Other parameters: | |||
@odata.type: #Microsoft.Media.JobOutputAsset |
True | string | Represents an Asset used as a job output. This is an obligatory parameter to set the assetName for the output. |
Priority |
string | The priority with which the job should be processed. Higher-priority jobs are processed before lower-priority jobs. If not set, the default is normal. |
Responses
Name | Type | Description |
---|---|---|
201 Created | Job | Created |
Other Status Codes | ErrorResponse | Detailed error information. |
Sample response
Status code: 201
Request Body:
{
"properties": {
"created": "2025-06-18T15:38:21.2990342Z",
"state": "Queued",
"input": {
"inputs": [
{
"assetName": "your-asset-name",
"start": {
"time": "PT10S",
"@odata.type": "#Microsoft.Media.AbsoluteClipTime"
},
"end": {
"time": "PT30S",
"@odata.type": "#Microsoft.Media.AbsoluteClipTime"
},
"inputDefinitions": [],
"@odata.type": "#Microsoft.Media.JobInputAsset"
},
{
"assetName": "your-asset-name2",
"start": {
"time": "PT30S",
"@odata.type": "#Microsoft.Media.AbsoluteClipTime"
},
"end": {
"time": "PT40S",
"@odata.type": "#Microsoft.Media.AbsoluteClipTime"
},
"inputDefinitions": [],
"@odata.type": "#Microsoft.Media.JobInputAsset"
}
],
"@odata.type": "#Microsoft.Media.JobInputSequence"
},
"lastModified": "2025-06-18T15:38:21.2990342Z",
"outputs": [
{
"assetName": "stitch1-name",
"@odata.type": "#Microsoft.Media.JobOutputAsset",
"state": "Queued",
"progress": 0,
"label": "BuiltInStandardEncoderPreset_0"
}
],
"priority": "Normal"
},
"systemData": {
"createdBy": "system",
"createdByType": "Application",
"createdAt": "2025-06-18T15:38:21.2990342Z",
"lastModifiedBy": "system",
"lastModifiedByType": "Application",
"lastModifiedAt": "2025-06-18T15:38:21.2990342Z"
},
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/mrg-yourresourceGroupName/providers/Microsoft.Media/mediaServices/default/transforms/StandardEncoder-AdaptiveStreaming/jobs/your-job-name",
"name": "your-job-name",
"type": "Microsoft.Media/mediaservices/transforms/jobs"
}
Considerations
Timing
- If no timing is specified, the entire source video will be used.
Limitations
- RMS supports stitching of video only; audio-only files are not supported.
- Stitching functionality is not available in Azure Media Services Explorer.
Quality and resolution
- Videos with different resolutions can be stitched together automatically.
- When using transforms like Adaptive Bitrate, RMS automatically analyzes all input videos and uses the highest quality source as the reference for the output quality ladder.
- Example: stitching 720p and 1080p videos creates an adaptive ladder with the highest input resolution of 1080p.
Mixed format support
- Videos with different frame rates (FPS) can be stitched.
- Different input video formats are supported.
Troubleshooting
Encountering issues with video stitching jobs? Here are common problems and their solutions to restore your content processing:
- Verify that all start and end times are within the source video duration.
-
Example: Asset has 45s in total timeline with start:
PT10S
, end:PT05S
(end is 5s longer than the timeline).
-
Example: Asset has 45s in total timeline with start:
- Check that the start time is less than the end time for each clip.
-
Example: Asset with start:
PT30S
, end:PT10SS
(end 10s is before start).
-
Example: Asset with start:
- Ensure timing values use a valid ISO 8601 format with no negative values, e.g.
PT-10S
. - For clips from the same source asset, make sure time ranges don't overlap.
- Example: Using 0s-30s of asset 1 + 20s-50s of the same asset 1 would have an overlapping of 10 seconds.
To view job details, including subclip boundaries and timing information, make a GET request to retrieve the job information.
Jobs with Error status include a complete error stack to help you address specific issues. If the error message isn't clear, contact Ravnur for assistance.