# Rivendell Web Interface API

### Fred Gleason

## Data Types

Table 1. Data Types

TYPE | DESCRIPTION
--- | ---
DateTime | xs:dateTime format string: `YYYY`-`MM`-`DD`T`HH`:`MM`:`SS`[Z]|[+`HH`:`MM`]|[-`HH`:`MM`] If no timezone information is specified, all values will be assumed to be in the local timezone of the processing system.
Date | xs:date format string: `YYYY`-`MM`-`DD`[Z]|[+`HH`:`MM`]|[-`HH`:`MM`] If no timezone information is specified, all values will be assumed to be in the local timezone of the processing system.
Time | xs:time format string: `HH`:`MM`:`SS`[Z]|[+`HH`:`MM`]|[-`HH`:`MM`] If no timezone information is specified, all values will be assumed to be in the local timezone of the processing system.
String | Text data, encoded

## Result Reporting

Commands that return an error or do not return specialized data types (e.g. audio data for the Export command) will return an XML document describing the result of the command, in the following format:

    <RDWebResult>
      <ResponseCode>resp_code</ResponseCode>
      <ErrorString>resp_string</ErrorString>
      <AudioConvertError>conv_error_code</AudioConvertError>
    </RDWebResult>

`resp_code`

  The HTTP result code, as defined in RFC2616

`resp_string`

  A text string describing the result, suitable for displaying in a UI

`conv_error_code`

  An extended error code from the audio converter routines. These values are defined in the `RDAudioConvert::ErrorCode` enumeration in `lib/rdaudioconvert.h`. This parameter is optional.

## AddCart

### Add a new cart

Command Code: `RDXPORT_COMMAND_ADDCART`

Required User Permissions: `Create Carts`

A `403` error will be returned if the requested cart number is not within the configured range for the specified group and 'Enforce Cart Range' is set in RDAdmin->ManageGroups.

Table 2. AddCart Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 12 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
GROUP_NAME | Name of Group | Mandatory
TYPE | Cart type | Valid values are "audio" or "macro"
CART_NUMBER | Number of Cart | Optional, default is to use next available cart number for specified group

## AddCut

### Add a new cut to an existing cart

Command Code: `RDXPORT_COMMAND_ADDCUT`

Required User Permissions: `Edit Audio`

A `404` error will be returned if the requested cart number is not authorized for the specified Rivendell user in RDAdmin->ManageUsers->AssignGroupPerms.

Table 3. AddCut Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 10 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
CART_NUMBER | Number of Cart | Mandatory

## AssignSchedCode

### Assign a scheduler code to an existing cart

Command Code: `RDXPORT_COMMAND_ASSIGNSCHEDCODE`

Required User Permissions: `Modify Carts`

A `404` error will be returned if the specified cart number is not authorized for the specified Rivendell user in RDAdmin->ManageUsers->AssignGroupPerms.

Table 4. AssignSchedCode Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 25 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
CART_NUMBER | Number of Cart | Mandatory
CODE | Scheduler Code to assign | Mandatory

## AudioInfo

### Get information about an entry in the audio store

Command Code: `RDXPORT_COMMAND_AUDIOINFO`

Required User Permissions: none

Table 5. AudioInfo Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 19 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
CART_NUMBER | Number of Cart | Mandatory
CUT_NUMBER | Number of Cut | Mandatory

## AudioStore

### Get information about the audio store

Command Code: `RDXPORT_COMMAND_AUDIOSTORE`

Required User Permissions: none

Table 6. AudioStore Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 23 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory

## DeleteAudio

### Delete PCM/MPEG data from the audio store

Command Code: `RDXPORT_COMMAND_DELETEAUDIO`

Required User Permissions: `Delete Carts`

Table 7. DeleteAudio Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 3 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
CART_NUMBER | Number of Cart | Mandatory
CUT_NUMBER | Number of Cut | Mandatory

## EditCart

### Write metadata changes for an existing cart into the database

Command Code: `RDXPORT_COMMAND_EDITCART`

Required User Permissions: `Modify Carts`

A `404` error will be returned if the requested cart belongs to a group that is not authorized for the specified Rivendell user in RDAdmin->ManageUsers->AssignGroupPerms, or if it is attempted to assign the cart to such a group.

A `409` error will be returned if the requested cart's number falls outside the valid range for the requested GROUP_NAME.

If the tags for an 'optional' field are omitted, then the respective parameter on the target cart will be left unchanged.

Table 8. EditCart Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 14 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
CART_NUMBER | Number of Cart | Mandatory
INCLUDE_CUTS | Include cut data in return, 0 = no, 1 = yes | Optional, default is 0
GROUP_NAME | Set Rivendell group | Optional
TITLE | Set Title | Optional
ARTIST | Set Artist | Optional
ALBUM | Set Album | Optional
YEAR | Set Year | Optional
LABEL | Set Record Label | Optional
CLIENT | Set Client | Optional
AGENCY | Set Agency | Optional
PUBLISHER | Set Publisher | Optional
COMPOSER | Set Composer | Optional
USER_DEFINED | Set User Defined | Optional
USER_CODE | Set User Code | Optional
ENFORCE_LENGTH | Set Enforce Length State | Optional, Numeric, 0 = No, 1 = Yes
FORCED_LENGTH | Set Forced Length | Optional, in milliseconds
ASYNCHRONOUS | Set Asynchronous | Optional, Numeric, 0 = No, 1 = Yes
OWNER | Set Owner | Optional
NOTES | Set Notes Text | Optional

## EditCut

### Write metadata changes for an existing cut into the database

Command Code: `RDXPORT_COMMAND_EDITCUT`

Required User Permissions: `Edit Audio`

A `404` error will be returned if the requested cart belongs to a group that is not authorized for the specified Rivendell user in RDAdmin->ManageUsers->AssignGroupPerms.

If the tags for an 'optional' field are omitted, then the respective parameter on the target cart will be left unchanged.

Table 9. EditCut Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 15 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
CART_NUMBER | Number of Cart | Mandatory
CUT_NUMBER | Number of Cut | Mandatory
EVERGREEN | Set the Evergreen Falg, valid values are 0 = no, 1 = yes | Optional
DESCRIPTION | Set Description | Optional
OUTCUE | Set Outcue | Optional
ISRC | Set International Standard Recording Code | Optional
ISCI | Set Internatinal Standardized Commercial Identifier | Optional
START_DATETIME | Set Start Date/Time | Optional, RFC-822 format
END_DATETIME | Set End Date/Time | Optional, RFC-822 format
MON | Set Monday daypart flag | Optional, 0 = no, 1 = yes
TUE | Set Tuesday daypart flag | Optional, 0 = no, 1 = yes
WED | Set Wedensday daypart flag | Optional, 0 = no, 1 = yes
THU | Set Thursday daypart flag | Optional, 0 = no, 1 = yes
FRI | Set Friday daypart flag | Optional, 0 = no, 1 = yes
SAT | Set Saturday daypart flag | Optional, 0 = no, 1 = yes
SUN | Set Sunday daypart flag | Optional, 0 = no, 1 = yes
START_DAYPART | Set Start daypart time | Optional, RFC-822 format
END_DAYPART | Set End daypart time | Optional, RFC-822 format
WEIGHT | Set rotation weight | Optional, numeric
START_POINT | Set Start Marker position | Optional, mS from absolute start of audio data
END_POINT | Set End Marker position | Optional, mS from absolute start of audio data
FADEUP_POINT | Set Fadeup Marker position | Optional, mS from absolute start of audio data
FADEDOWN_POINT | Set Fadedown Marker position | Optional, mS from absolute start of audio data
SEGUE_START_POINT | Set Segue Start Marker position | Optional, mS from absolute start of audio data
SEGUE_END_POINT | Set Segue End Marker position | Optional, mS from absolute start of audio data
HOOK_START_POINT | Set Hook Start Marker position | Optional, mS from absolute start of audio data
HOOK_END_POINT | Set Hook End Marker position | Optional, mS from absolute start of audio data
TALK_START_POINT | Set Talk Start Marker position | Optional, mS from absolute start of audio data
TALK_END_POINT | Set Talk End Marker position | Optional, mS from absolute start of audio data

## Export

### Export audio data from the audio store

Command Code: `RDXPORT_COMMAND_EXPORT`

Required User Permissions: none

Table 10. Export Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 1 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
CART_NUMBER | Number of Cart | Mandatory
CUT_NUMBER | Number of Cut | Mandatory
FORMAT | Encoding format of exported data | Mandatory, 0 = PCM16 WAV, 2 = MPEG L2 native, 3 = MPEG L3 native, 4 = FLAC, 5 = OggVorbis, 6 = MPEG L2 WAV, 7 = PCM24 WAV
CHANNELS | Number of audio channels | Mandatory
SAMPLE_RATE | Sample rate | Mandatory, in samples/sec
BIT_RATE | Bit rate | Mandatory, set to '0' for PCM or VBR
QUALITY | Quality Level | Mandatory, used only by OggVorbis, set to '0' for others
START_POINT | Start point of audio export | Mandatory, mS from absolute start of stored audio
END_POINT | End point of audio export | Mandatory, mS from absolute start of stored audio
NORMALIZATION_LEVEL | Normalization leve, in dBFS | Mandatory, 0 = No normalization
ENABLE_METADATA | Include metadata in export | Mandatory, 0 = no, 1 = yes

## ExportPeaks

### Export audio peak data from the audio store

Command Code: `RDXPORT_COMMAND_EXPORT`

Required User Permissions: none

A `404` error will be returned if the requested cart is not authorized for the specified Rivendell user in RDAdmin->ManageUsers->AssignGroupPerms.

Table 11. ExportPeaks Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 16 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
CART_NUMBER | Number of Cart | Mandatory
CUT_NUMBER | Number of Cut | Mandatory

## Import

### Import audio data into the audio store

Command Code: `RDXPORT_COMMAND_IMPORT`

Required User Permissions: `Edit Audio`

A `404` error will be returned if the requested cart is not authorized for the specified Rivendell user in RDAdmin->ManageUsers->AssignGroupPerms.

NOTE: The method must be called with 'multipart/form-data' encoding.

Table 12. Import Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 2 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
CART_NUMBER | Number of Cart | Mandatory
CUT_NUMBER | Number of Cut | Mandatory
CHANNELS | Number of audio channels | Mandatory
NORMALIZATION_LEVEL | Normalization level, in dBFS | Mandatory, 0 = no normalization
AUTOTRIM_LEVEL | Autotrim level, in dBFS | Mandatory, 0 = no autotrim
USE_METADATA | Apply source metadata to cart | Mandatory, 0 = No, 1 = Yes
CREATE | Create cart/cut if it does not exist | Optional, 0 = No, 1 = Yes
GROUP_NAME | Add newly created cart/cut to specified group. | Optional
FILENAME | Binary file data | Mandatory

## ListCart

### Return information about a specified cart

Command Code: `RDXPORT_COMMAND_LISTCART`

Required User Permissions: none

A `404` error will be returned if the requested cart belongs to a group that is not authorized for the specified Rivendell user in RDAdmin->ManageUsers->AssignGroupPerms.

Table 13. ListCart Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 7 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
CART_NUMBER | Number of Cart | Mandatory
INCLUDE_CUTS | Include cut information in return | Optional, 0 = no, 1 = yes, default is 1

## ListCarts

### Return information about a set of carts

Command Code: `RDXPORT_COMMAND_LISTCARTS`

Required User Permissions: none

Only those carts that belong to groups authorized for the specified Rivendell user in RDAdmin->ManageUsers->AssignGroupPerms will be returned.

Table 14. ListCarts Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 6 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
GROUP_NAME | Limit returns to members of specified group | Optional, default is to search all available carts
INCLUDE_CUTS | Include cut information in return | Optional, 0 = no, 1 = yes, default is 1
FILTER | Limit returns to carts containing specified space-separated keyword(s) | Optional, default is to apply no filtering
TYPE | Limit returns to carts of the specified type | Optional, valid values are 'audio' or 'macro'

## ListCartSchedCodes

### Return information about all scheduler codes assigned to a cart

Command Code: `RDXPORT_COMMAND_LISTCARTSCHEDCODES`

Required User Permissions: none

A `404` error will be returned if the requested cart belongs to a group that is not authorized for the specified Rivendell user in RDAdmin->ManageUsers->AssignGroupPerms.

Table 15. ListCartSchedCodes Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 27 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
CART_NUMBER | Number of Cart | Mandatory

## ListCut

### Return information about a specified cut

Command Code: `RDXPORT_COMMAND_LISTCUT`

Required User Permissions: none

A `404` error will be returned if the requested cart belongs to a group that is not authorized for the specified Rivendell user in RDAdmin->ManageUsers->AssignGroupPerms.

Table 16. ListCut Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 8 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
CART_NUMBER | Number of Cart | Mandatory
CUT_NUMBER | Number of Cut | Mandatory

## ListCuts

### Return information about all cuts belonging to a cart

Command Code: `RDXPORT_COMMAND_LISTCUTS`

Required User Permissions: none

A `404` error will be returned if the requested cart belongs to a group that is not authorized for the specified Rivendell user in RDAdmin->ManageUsers->AssignGroupPerms.

Table 17. ListCuts Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 9 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
CART_NUMBER | Number of Cart | Mandatory

## ListGroup

### Return information about a specified group

Command Code: `RDXPORT_COMMAND_LISTGROUP`

Required User Permissions: none

A `404` error will be returned if the requested group is not authorized for the specified Rivendell user in RDAdmin->ManageUsers->AssignGroupPerms.

Table 18. ListGroup Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 5 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
GROUP_NAME | Name of group | Mandatory

## ListGroups

### Return information about all available groups

Command Code: `RDXPORT_COMMAND_LISTGROUPS`

Required User Permissions: none

The set of returned groups will be tailored according to what the specified Rivendell user is authorized to see in RDAdmin->ManageUsers->AssignGroupPerms.

Table 19. ListGroups Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 4 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory

## ListLog

### Return a listing of the specified log

Command Code: `RDXPORT_COMMAND_LISTLOG`

Required User Permissions: none

Table 20. ListLog Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 22 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
NAME | The name of the log | Mandatory

## ListLogs

### Return information about all available logs

Command Code: `RDXPORT_COMMAND_LISTLOGS`

Required User Permissions: none

Table 21. ListLogs Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 20 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
SERVICE_NAME | Limits returns to logs that are owned by specified service | Optional. Default is to return all logs.
TRACKABLE | Limits returns to logs that contain one or more voicetrack slots | Optional, valid values 0=no, 1=yes. Default is to return all logs

## ListSchedulerCodes

### Return information about all available scheduler codes

Command Code: `RDXPORT_COMMAND_LISTSCHEDCODES`

Required User Permissions: none

Table 22. ListSchedCodes Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 24 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory

## ListServices

### Return information about all available services

Command Code: `RDXPORT_COMMAND_LISTSERVICES`

Required User Permissions: none

Table 23. ListServices Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 21 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
TRACKABLE | Limits returns to services that have a valid voicetracking configuration | Optional, valid values 0=no, 1=yes. Default is to return all services

## RemoveCart

### Remove a cart from the Library

Command Code: `RDXPORT_COMMAND_REMOVECART`

Required User Permissions: `Delete Cart`

Table 24. RemoveCart Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 13 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
CART_NUMBER | Number of cart | Mandatory

## RemoveCut

### Remove an existing cut from a cart

Command Code: `RDXPORT_COMMAND_REMOVECUT`

Required User Permissions: `Edit Audio`

Table 25. RemoveCut Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 11 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
CART_NUMBER | Number of cart | Mandatory
CUT_NUMBER | Number of cut | Mandatory

## TrimAudio

### Return a time pointer to the first or last instance of a particular level in a cut.

Command Code: `RDXPORT_COMMAND_TRIMAUDIO`

Required User Permissions: `Edit Audio`

A `404` error will be returned if the requested cart is not authorized for the specified Rivendell user in RDAdmin->ManageUsers->AssignGroupPerms.

Table 26. TrimAudio Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 17 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
CART_NUMBER | Number of cart | Mandatory
CUT_NUMBER | Number of cut | Mandatory
TRIM_LEVEL | Level in 1/100 dB, relative to Rivendell reference level (-16 dBFS) | Mandatory

## UnassignSchedCode

### Unassign a scheduler code from an existing cart

Command Code: `RDXPORT_COMMAND_UNASSIGNSCHEDCODE`

Required User Permissions: `Modify Carts`

A `404` error will be returned if the specified cart number is not authorized for the specified Rivendell user in RDAdmin->ManageUsers->AssignGroupPerms.

Table 27. UnassignSchedCode Call Fields

FIELD NAME | MEANING | REMARKS
--- | --- | ---
COMMAND | 26 | Mandatory
LOGIN_NAME | Rivendell User Name | Mandatory
PASSWORD | Login Password | Mandatory
CART_NUMBER | Number of Cart | Mandatory
CODE | Scheduler Code to assign | Mandatory