Rivendell Web Interface API

Fred Gleason


Table of Contents

Data Types
Result Reporting
AddCart
AddCut
AssignSchedCode
AudioInfo
AudioStore
DeleteAudio
EditCart
EditCut
Export
ExportPeaks
Import
ListCart
ListCarts
ListCartSchedCodes
ListCut
ListCuts
ListGroup
ListGroups
ListLog
ListLogs
ListSchedulerCodes
ListServices
RemoveCart
RemoveCut
TrimAudio
UnassignSchedCode

Data Types

Table 1. Data Types

TYPE DESCRIPTION
DateTime

xs:dateTime format string: YYYY-MM-DDTHH: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