General Notes
- All paths above are relative to the REST endpoint base (something like http://your.server/files)
- If the service is down or not working it will return a status 503, this means the the underlying service is not working and is either restarting or has failed
- A status code 500 means a general failure has occurred which is not recoverable and was not anticipated. In other words, there is a bug! You should file an error report with your server logs from the time when the error occurred: Opencast Issue Tracker
Table of Contents
- GET /profiles.xml
- GET /profile/{id}.xml
- POST /composite
- POST /concat
- POST /convertimage
- POST /convertimagesync
- POST /demux
- POST /encode
- POST /image
- POST /imagesync
- POST /imagetovideo
- POST /multiencode
- POST /mux
- POST /parallelencode
- POST /processsmil
- POST /trim
Read methods
Method / Path: | GET /profiles.xml |
---|---|
Description: | Retrieve the encoding profiles |
Path params: | NONE |
Optional (query) params: | NONE |
Response formats: | text/xml |
Status codes: | 200: OK, Results in an xml document describing the available encoding profiles |
Returned Entity Schema: | |
Testing: |
Sample:
/profiles.xml
/composer/ffmpeg/profiles.xml
|
Method / Path: | GET /profile/{id}.xml |
---|---|
Description: | Retrieve an encoding profile |
Path params: | id: the profile ID |
Optional (query) params: | NONE |
Response formats: | text/xml |
Status codes: |
200: OK, Results in an xml document describing the requested encoding profile 404: Not Found, If profile has not been found |
Testing: |
Sample:
/profile/{id}.xml
Testing form (click to reveal)
|
Write methods
Method / Path: | POST /composite |
---|---|
Description: | Starts a video compositing process, based on the specified resolution, encoding profile ID, the source elements and their layouts |
Path params: | NONE |
Required (form) params: |
compositeSize: The resolution size of the resulting video as JSON
lowerTrack: The lower source track containing the lower video lowerLayout: The lower layout containing the JSON definition of the layout profileId: The encoding profile to use |
Optional (form) params: |
upperTrack:
The upper source track containing the upper video upperLayout: The upper layout containing the JSON definition of the layout watermarkTrack: The watermark source attachment containing watermark image watermarkLayout: The watermark layout containing the JSON definition of the layout background(Default value=black): The background color audioSourceName(Default value=both): The name of the audio source (lower or upper or both) |
Response formats: | text/xml |
Status codes: |
200: OK, Results in an xml document containing the compound video track 400: Bad Request, If required parameters aren't set or if the source elements aren't from the right type |
Testing: |
Sample:
/composite
Testing form (click to reveal)
|
Method / Path: | POST /concat |
---|---|
Description: | Starts a video concating process from multiple videos, based on the specified encoding profile ID and the source tracks |
Path params: | NONE |
Required (form) params: |
sourceTracks: The source tracks to concat as XML
profileId: The encoding profile to use |
Optional (form) params: |
outputDimension:
The resolution dimension of the concat video as JSON outputFrameRate: The frame rate of the concat video (should be positive, e.g. 25.0). Negative values and zero will cause no FFmpeg fps filter to be used in the filter chain. sameCodec(Default value=false): The source files have the same codecs and should not be re-encoded |
Response formats: | text/xml |
Status codes: |
200: OK, Results in an xml document containing the video track 400: Bad Request, If required parameters aren't set or if sourceTracks aren't from the type Track or not at least two tracks are present |
Testing: |
Sample:
/concat
Testing form (click to reveal)
|
Method / Path: | POST /convertimage |
---|---|
Description: | Starts an image conversion process, based on the specified encoding profile ID and the source image |
Path params: | NONE |
Required (form) params: |
sourceImage: The original image
profileId: A comma separated list of encoding profiles to use |
Optional (form) params: | NONE |
Response formats: | text/xml |
Status codes: |
200: OK, Results in an xml document containing the image attachment 400: Bad Request, If required parameters aren't set or if sourceImage isn't from the type Attachment |
Testing: |
Sample:
/convertimage
Testing form (click to reveal)
|
Method / Path: | POST /convertimagesync |
---|---|
Description: | Synchronously converts an image, based on the specified encoding profiles and the source image |
Path params: | NONE |
Required (form) params: |
sourceImage: The original image
profileIds: The encoding profiles to use |
Optional (form) params: | NONE |
Response formats: | text/xml |
Status codes: |
200: OK, Results in an xml document containing the image attachments 400: Bad Request, If required parameters aren't set or if sourceImage isn't from the type attachment |
Testing: |
Sample:
/convertimagesync
Testing form (click to reveal)
|
Method / Path: | POST /demux |
---|---|
Description: | Starts an demux process that produces multiple outputs, based on the specified encoding profile ID and the track |
Path params: | NONE |
Required (form) params: |
sourceTrack: The track containing the stream
profileId: The encoding profile to use |
Optional (form) params: | NONE |
Response formats: | text/xml |
Status codes: |
200: OK, Results in an xml document containing the job for the encoding task 400: Bad Request, If required parameters aren't set or if sourceTrack isn't from the type Track |
Testing: |
Sample:
/demux
Testing form (click to reveal)
|
Method / Path: | POST /encode |
---|---|
Description: | Starts an encoding process, based on the specified encoding profile ID and the track |
Path params: | NONE |
Required (form) params: |
sourceTrack: The track containing the stream
profileId: The encoding profile to use |
Optional (form) params: | NONE |
Response formats: | text/xml |
Status codes: |
200: OK, Results in an xml document containing the job for the encoding task 400: Bad Request, If required parameters aren't set or if sourceTrack isn't from the type Track |
Testing: |
Sample:
/encode
Testing form (click to reveal)
|
Method / Path: | POST /image |
---|---|
Description: | Starts an image extraction process, based on the specified encoding profile ID and the source track |
Path params: | NONE |
Required (form) params: |
sourceTrack: The track containing the video stream
profileId: The encoding profile to use |
Optional (form) params: |
time:
The number of seconds (many numbers can be specified, separated by semicolon) into the video to extract the image properties: An optional set of key=value\n properties |
Response formats: | text/xml |
Status codes: |
200: OK, Results in an xml document containing the image attachment 400: Bad Request, If required parameters aren't set or if sourceTrack isn't from the type Track |
Notes: |
|
Testing: |
Sample:
/image
Testing form (click to reveal)
|
Method / Path: | POST /imagesync |
---|---|
Description: | Synchronously extracts an image, based on the specified encoding profile ID and the source track |
Path params: | NONE |
Required (form) params: |
sourceTrack: The track containing the video stream
profileId: The encoding profile to use |
Optional (form) params: | time: The number of seconds (many numbers can be specified, separated by semicolon) into the video to extract the image |
Response formats: | text/xml |
Status codes: |
200: OK, Results in an xml document containing the image attachment 400: Bad Request, If required parameters aren't set or if sourceTrack isn't from the type Track |
Notes: |
|
Testing: |
Sample:
/imagesync
Testing form (click to reveal)
|
Method / Path: | POST /imagetovideo |
---|---|
Description: | Starts an image converting process to a video, based on the specified encoding profile ID and the source image attachment |
Path params: | NONE |
Required (form) params: |
sourceAttachment: The attachment containing the image to convert
profileId: The encoding profile to use |
Optional (form) params: | time(Default value=1): The resulting video time in seconds |
Response formats: | text/xml |
Status codes: |
200: OK, Results in an xml document containing the video track 400: Bad Request, If required parameters aren't set or if sourceAttachment isn't from the type Attachment |
Testing: |
Sample:
/imagetovideo
Testing form (click to reveal)
|
Method / Path: | POST /multiencode |
---|---|
Description: | Starts an encoding process that produces multiple outputs, based on the specified encoding profile ID and the track |
Path params: | NONE |
Required (form) params: |
sourceTrack: The track containing the stream
profileIds: The comma-delimited encoding profiles to use |
Optional (form) params: | NONE |
Response formats: | text/xml |
Status codes: |
200: OK, Results in an xml document containing the job for the encoding task 400: Bad Request, If required parameters aren't set or if sourceTrack isn't from the type Track |
Testing: |
Sample:
/multiencode
Testing form (click to reveal)
|
Method / Path: | POST /mux |
---|---|
Description: | Starts an encoding process, which will mux the two tracks using the given encoding profile |
Path params: | NONE |
Required (form) params: |
sourceAudioTrack: The track containing the audio stream
sourceVideoTrack: The track containing the video stream profileId: The encoding profile to use |
Optional (form) params: | NONE |
Response formats: | text/xml |
Status codes: |
200: OK, Results in an xml document containing the job for the encoding task 400: Bad Request, If required parameters aren't set or if the source tracks aren't from the type Track |
Testing: |
Sample:
/mux
Testing form (click to reveal)
|
Method / Path: | POST /parallelencode |
---|---|
Description: | Starts an encoding process, based on the specified encoding profile ID and the track |
Path params: | NONE |
Required (form) params: |
sourceTrack: The track containing the stream
profileId: The encoding profile to use |
Optional (form) params: | NONE |
Response formats: | text/xml |
Status codes: | 200: OK, Results in an xml document containing the job for the encoding task |
Testing: |
Sample:
/parallelencode
Testing form (click to reveal)
|
Method / Path: | POST /processsmil |
---|---|
Description: | Starts an encoding process, based on the tracks and edit points in the smil and specified encoding profile IDs |
Path params: | NONE |
Required (form) params: |
smilAsXml: The smil containing the tracks and edit points
profileIds: The encoding profiles to use |
Optional (form) params: |
trackId:
The id (paramgroup) of the track to encode mediaType(Default value=o): MediaType - v for video only, a for audio only, audiovisual otherwise |
Response formats: | text/xml |
Status codes: |
200: OK, Results in an xml document containing the job for the encoding task 400: Bad Request, If required parameters aren't set or if sourceTrack isn't from the type Track |
Testing: |
Sample:
/processsmil
Testing form (click to reveal)
|
Method / Path: | POST /trim |
---|---|
Description: | Starts a trimming process, based on the specified track, start time and duration in ms |
Path params: | NONE |
Required (form) params: |
sourceTrack: The track containing the stream
profileId: The encoding profile to use for trimming start: The start time in milisecond duration: The duration in milisecond |
Optional (form) params: | NONE |
Response formats: | text/xml |
Status codes: |
200: OK, Results in an xml document containing the job for the trimming task 400: Bad Request, If the start time is negative or exceeds the track duration 400: Bad Request, If the duration is negative or, including the new start time, exceeds the track duration |
Testing: |
Sample:
/trim
Testing form (click to reveal)
|