RATS format resource

Overview

The RATS API's format resource creates a (transcoding) format profile. A format profile determines the exact transcoding format, which is used for launching transcoding jobs.

Note that in most setups, it suffices to pre-define a number of format profiles via the RATS web-application and use their id when launching jobs from your client application.

Actions

• GET http://rats.{cdn0x}.rambla.be/format/ : get a list of existing format profiles
• POST http://rats.{cdn0x}.rambla.be/format/ : create a new format profile
• GET http://rats.{cdn0x}.rambla.be/format/{ID}/ : get an existing format profile
• POST http://rats.{cdn0x}.rambla.be/format/{ID}/ : overwrite an existing format profile
• DELETE http://rats.{cdn0x}.rambla.be/format/{ID} : delete an existing format profile

Content

Params

A format instance consists of a bunch of parameters, together forming a reusable profile for transcoding operations.

• id : unique (numerical) identifier for the format profile, given by the RATS server when creating it
• name : a unique name for the format profile, given by the client in the request
• description : a description of the format profile
• category : can be 'formats' (= default) or 'devices'
• container : video container format, can be avi, mp4, 3gp, psp, mpeg, mpegts, dvd, flv, svcd, vcd, vob, asf, mov, rm, mjpeg, mpeg2video, 3g2, mp3, ogg
• video_codec : video codec; can be mpeg4, xvid, flv, h263, mjpeg, mpeg1video, mpeg2video, qtrle, svq3, wmv1, wmv2, huffyuv, rv20, h264
• video_bitrate : video bitrate in kbit/s, value must be between 50 and 10000
• video_cq : compression quality, can be used to keep constant quality whith varying resolutions. The value must be between 0.05 and 0.50 (default = 0.10) and may have 2 digits after the comma. Is only used when video_bitrate is set to 0.
• video_fps : frames per second; can be 7.5, 10.0, 14.985, 15.0, 23.98, 25.0, 29.97, 30.0
• video_width : width in pixel of the image, must be between 50 and 1920, must be multiples of 16
• video_height : height in pixel of the image, must be between 50 and 1280. If 0, it will be calculated automatically, must be multiples of 16
• video_deinterlace : 'no' (no deinterlacing), 'md' (median deinterlacer), 'li' (linear interpolate) or 'ci' (cubic interpolate)
• video_passes : 1 = faster, 2 = better quality
• video_crop_bottom, video_crop_top, video_crop_left, video_crop_right : number of pixels to cut from the original video before encoding
• video_aspect_ratio : decimal value eg. 1.3334 : pass aspect ratio to mpeg2 or mpeg4 header and used by player (can also be used to calculate height from widht, if not set)
• audio_channel : Audio channel, can be 0 to disable audio, 1 for mono and 2 for stereo
• audio_codec : Audio codec; can be mp3, mp2, aac, pcm, amr_nb, ac3, vorbis, flac, pcm_u8.
• audio_bitrate : Audio bitrate in kbit/s, up to 512kbits
• audio_sample_rate : Sample rate; can be 8000, 11025, 16000, 22000, 22050, 24000, 32000, 44000, 44100, 48000
• audio_track_mapping : 0.1:0.1,0.2:0.2 track mappings as seen by ffmpeg, separated by comma. If the source file has multiple audio tracks (eg broadcast 1 with voice-over, 1 without) it can be mapped to output audio tracks if supported by output format (eg mp4). If empty only 1 track is used for encoding to output file.
• overlay : ID of an existing overlay file
• input : ID of an existing input profile. Note that when an input profile is passed along with the job request, it will override the profile specified in the format profile.
• output : ID of an existing output profile
• device : Only set this if special transcoding options are needed for a hardware device, and you know what you're doing. Otherwise just leave it 'as is'. Currently supported choices: 'None', 'iphone', 'baseline', 'main', 'baseline_adaptive', 'main_adaptive', 'Custom'. If you need support for specific hardware, please contact Rambla.
• slug : short and alphanumerical only format name. If present, it will be appended (using a dash) to the transcoded file name: {filename}-{slug}.{extension}. A slug should be used in case the format is being used to produce files for adaptive streaming (in which case the slug allows users to easily see the difference between the .mp4 files with different bitrates).
• playlist : Used to generate/export a SMIL file for adaptive streaming. If a job request uses a 'formatgroup' (instead of a 'format'), the playlist name(s) inside each format will be used to determine of which SMIL file(s) the transcoded file must be part. The playlist element may be repeated, to make the transcoded files a part of multiple SMIL files.

Action Details

GET format list

GET http://rats.{cdn0x}.rambla.be/format/

Retrieves a list of format instances (= transcoding profiles) available to the user.

Query String Arguments

Apart from the common query-string arguments for RATS, the format resource allows some additional query-string arguments to be passed.

• container : retrieve only the format instances with this type of container
• video_codec : retrieve only the format instances with this type of video_codec
• audio_codec : retrieve only the format instances with this type of audio_codec

E.g. http://rats.{cdn0x}.rambla.be/format/?container=mp4;video_codec=h264

Response

Retrieves a list (feed) of existing format entries (see RAWS Atom Response Format for the general structure). Each entry represents an format instance that is available on the RATS server.

GET format

GET http://rats.{cdn0x}.rambla.be/format/{ID}/

Retrieves a single format instance. The ID refers to the numerical identifier of the format instance on the RATS server.

POST format

POST http://rats.{cdn0x}.rambla.be/format/

Creates a new format instance on the RATS Server.

POST http://rats.{cdn0x}.rambla.be/format/{ID}/

Overwrites an existing format instance on the RATS Server.

Entry Content

In both cases, the body of the request should contain a complete format entry. Exactly which parameters are required depends on the kind of transcoding operation.

• Always required are raws:name and raws:container.
• If the transcoding involves video, the raws:video_codec will determine which other raws:video_ parameters are also required.
• If the transcoding (also) involves audio, the raws:audio_codec will determine which other raws:audio_ parameters are also required. See the list above for details. Note that all parameters belong to the raws namespace.

Response

When successful, the response will have a HTTP status code of 201. The response HTTP headers will also contain a Location Header, which specifies the RATS URI at which this new resource instance can be reached.

DELETE format

DELETE http://rats.{cdn0x}.rambla.be/format/{ID}/

Deletes an existing format instance on the RATS Server.

Response

When successful, the response will have a HTTP status code of 204 and no body.

Common Errors

• NoSuchResource (404 NOT FOUND), in case the format doesn't exist.

See RAWS Error Codes for more details.