GET /playlists

Description

The Playlists resource allows you to obtain a HLS or MPEG DASH playlist for any file encoded in MP4 format or any job with outputs in MP4 format. If you request the playlist for a job ID with multiple outputs in MP4 format, you will receive a playlist including each of the outputs as a representation (e.g. different resolutions or different bitrates). By listing selected output file IDs comma-separated in the file_id parameter, you can also pick just a subset of a job's outputs for the playlist (e.g. to exclude the 4K version).

The /playlists endpoint works very similar to the /files/downloads API: most of the query parameters available with /files/downloads are also available for /playlists, and temporary playlist URLs can also be created via HMAC-signing exactly the same way as for regular file downloads (see HMAC Signing of API Requests).

The /playlists endpoint can also remove time ranges from the source video directly inside the generated playlist (manifest-only cuts). The original media is never modified: the video segments overlapping a requested range are omitted from the playlist, and the audio is trimmed to match as far as possible. This is useful to strip out copyrighted content, ad breaks or any unwanted portion of a video before it is played back. See the d and drop parameters below.

Endpoints

• GET /playlists/hls.m3u8: Allows obtaining a HLS playlist of one or more file(s) encoded in MP4 format by a successfully finished conversion Job.
• GET /playlists/dash.mpd: Allows obtaining a MPEG DASH playlist of one or more file(s) encoded in MP4 format by a successfully finished conversion Job.

Authentication

• Optional: Bearer token or HMAC signature

Request Headers

• Authorization: Bearer [AUTH_TOKEN] (if provided)

Parameters

Query Parameters

• file_id: string (Optional)
  ID specifying one or more file(s) in the Files resource. The specified file(s) must be encoded in MP4 format. Multiple file IDs can be provided separated by commas — all file IDs must belong to the same job.
• job_id: string (Optional)
  Shortcut for selecting all the output file IDs of a given job. Equivalent to listing all output file IDs of a job comma-separated in the "file_id" parameter. The "file_id" and "job_id" parameters should not be used together.
• autograph_tag: string (Optional)
  A unique tag to be embedded dynamically with the resulting video stream for traceability via Xvid AutoGraph watermarking technology. Only set this parameter for files that have the "autograph": true property — do not set it otherwise!
• expiry_time: int (Optional)
  Desired expiry time (in seconds since epoch) for the playlist. The expiry time is attached to the sub-playlists and/or video segments referenced inside the playlist. Note: Epoch timestamps are UTC by definition — make sure to compute the value from the current UTC time, not your webserver's local time.
• anti_fraud: boolean (Optional)
  Enables features to prevent link sharing and detect fraud, like blocking users behind anonymizing proxies and blocking black-listed IPs of well-known (serial) pirates.
• ip: int (Optional)
  Allows only clients with the specified IP address to retrieve the playlist. The IP must be specified as a 32-bit integer (example: 192.168.2.1 -> (192 << 24) | (168 << 16) | (2 << 8) | 1 = 3232236033).
• d: string (Optional)
  Compact Base64URL-encoded list of original-media time ranges to remove from the playlist. Each range is encoded as a pair of LEB128 variable-length integers expressing, in 100 ms ticks, the media to keep after the previous removed range and the media to remove. For example, removing the ranges [20,30)s and [42,50)s is encoded as d=yAFkeFA. The d and drop parameters should not be used together.
• drop: string (Optional)
  Human-readable list of original-media time ranges (in seconds) to remove from the playlist, e.g. drop=20-30,42-50. Ranges may include one decimal place (tenths of a second), e.g. drop=20.5-30.2. The d and drop parameters should not be used together.

Example Request

curl -X GET "https://api.xvid.com/v1/playlists/hls.m3u8?autograph_tag=XVID_TEST&file_id=54820cec18bac397e161aebc" \
  -H "Authorization: Bearer AUTH_TOKEN"

curl -X GET "https://api.xvid.com/v1/playlists/dash.mpd?job_id=5daedac4e4b03303cd50b851&drop=100-200" \
  -H "Authorization: Bearer AUTH_TOKEN"

Example Response

HLS Playlist

#EXTM3U
#EXT-X-MEDIA:NAME="Xvid MediaHub Video",LANGUAGE="en",AUTOSELECT="yes",DEFAULT="yes",URI="https://autograph.xvid.com:443/api/v1/segments/job_id/5daedac4e4b03303cd50b851/base/547f3eede4b025bcbff38655%3Barchive%3B/tag/XVID_TEST/crypt_tag/O_NyeiFPPpPVZXmqcwEPLZ7vGTrFPMiAwcqMgttOEOlQ/client_id/57fc1561e4b09eea4328115e/user_id/547f3eede4b025bcbff38655/expiry_time/1683296550/sign/2d62b553801640170db28faad5cde5910589ac7d/map/true/url/5dafdac4e4b03703cd50b851/output_0/QIHoEmOnoxv5-0GovkRp66e5qK4fl7dchX_audio.m3u8",CODECS="mp4a.40.2",TYPE="AUDIO",GROUP-ID="audio"
#EXT-X-STREAM-INF:BANDWIDTH=8800000,AUDIO="audio",RESOLUTION=1920x1080,CODECS="avc1.640028,mp4a.40.2"
https://autograph.xvid.com:443/api/v1/segments/job_id/5daedac4e4b03303cd50b851/base/547f3eede4b025bcbff38655%3Barchive%3B/tag/XVID_TEST/crypt_tag/O_NyeiFPPpPVZXmqcwEPLZ7vGTrFPMiAwcqMgttOEOlQ/client_id/57fc1561e4b09eea4328115e/user_id/547f3eede4b025bcbff38655/expiry_time/1683296550/sign/2d62b553801640170db28faad5cde5910589ac7d/map/true/url/5daedac4e4b03703cd50b851/output_0/QIHoEmOnoxv5-0GovkRp66e5qK4fl7dchX_video.m3u8

Error Responses

400 Bad Request

{
  "error": {
    "error_code": "0x0050001",
    "error_message": "Invalid Input"
  }
}

When a malformed d or drop parameter is supplied, the response uses the drop-specific error code:

{
  "error": {
    "error_code": "0x0310001",
    "error_message": "Invalid drop parameter"
  }
}

403 Forbidden

{
  "error": {
    "error_code": "0x0000003",
    "error_message": "Invalid access token"
  }
}

404 Not Found

{
  "error": {
    "error_code": "0x0050005",
    "error_message": "File does not exist"
  }
}

413 Payload Too Large

Returned when the d parameter exceeds the supported encoded length or number of ranges:

{
  "error": {
    "error_code": "0x0310002",
    "error_message": "Drop parameter exceeds supported limits"
  }
}

422 Unprocessable Entity

Returned when the requested drop cannot be applied to the asset as a manifest-only edit. This includes edits that would leave no playable media, or assets whose segment structure cannot support the requested cuts (for example an audio coverage gap, missing segment timing metadata, or substantially misaligned rendition segment grids):

{
  "error": {
    "error_code": "0x0310003",
    "error_message": "Asset cannot support the requested manifest-only cuts"
  }
}

When the drop would remove all playable media, the dedicated error below is returned instead:

{
  "error": {
    "error_code": "0x0310004",
    "error_message": "Drop parameter would remove all playable media"
  }
}