Autres/Rivendellaudio
1
0
Fork 0
mirror of https://github.com/ElvishArtisan/rivendell.git synced 2025-05-19 14:43:30 +02:00
Code Issues Projects Releases Wiki Activity
Rivendellaudio/docs/apis/notification.xml
Fred Gleason ae3542f9a4 2022-11-02 Fred Gleason <fredg@paravelsystems.com> 
* Refactored rdcatch(1) and rdcatchd(8) to use the notification
	mechanism instead for distributing meter updates instead of the
	'Enable Metering' catch command.

Signed-off-by: Fred Gleason <fredg@paravelsystems.com>
2022-11-02 13:10:11 -04:00

866 lines
22 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="ISO-8859-1"?>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<info>
<title>Rivendell Notification Protocol</title>
<author>
<personname>
<firstname>Fred</firstname>
<surname>Gleason</surname>
<email>fredg@paravelsystems.com</email>
</personname>
</author>
</info>
<sect1 xml:id="overview">
<title>Overview</title>
<para>
This document defines the IP protocol used by Rivendell for real-time
communication between different modules and/or hosts. Messages are sent
by means of multicast UDP packets to port 20539. The IPv4 multicast group
address used is defined the in the SYSTEM.NOTIFICATION_ADDRESS database
field.
</para>
<para>
Update messages are textual, with individual fields delimited by
the ASCII SPACE character. They are formatted as follows:
</para>
<para>
<replaceable choice='req'>keyword</replaceable>
<replaceable choice='req'>arg1</replaceable>
<replaceable choice='req'>arg2</replaceable>
<replaceable choice='opt'>[...]</replaceable>
</para>
<para>
where <replaceable>keyword</replaceable> defines the class of message.
The following classes are defined:
</para>
<variablelist>
<varlistentry>
<term>Notifications</term>
<listitem>
<para>
Signals a change to a Rivendell database object.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Catch Events</term>
<listitem>
<para>
RDCatch state changes.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 xml:id="sect.notification_messages">
<title>Notification Messages</title>
<para>
Notification messages use the following format:
</para>
<para>
NOTIFY <replaceable choice='req'>type</replaceable>
<replaceable choice='req'>action</replaceable>
<replaceable choice='req'>id</replaceable>
</para>
<variablelist>
<varlistentry>
<term>
<replaceable>type</replaceable>
</term>
<listitem>
<para>
The database object type to which the message pertains.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<replaceable>action</replaceable>
</term>
<listitem>
<para>
The action being reported. The following actions are defined:
</para>
<variablelist>
<varlistentry>
<term>
ADD
</term>
<listitem>
<para>
The referenced object has just been added to the database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
DELETE
</term>
<listitem>
<para>
The referenced object has just been deleted from the database.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
MODIFY
</term>
<listitem>
<para>
The reference object has just been modified in the database.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>
<replaceable>id</replaceable>
</term>
<listitem>
<para>
Unique id of the object.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The following database object types are defined:
</para>
<sect2 xml:id="sect.notifications.object_types.cart">
<title>Carts</title>
<table xml:id="table.notifications.types.carts" frame="all" pgwide="0">
<title>Cart Fields</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="Field" colwidth="2.0*"/>
<colspec colname="Value" colwidth="2.0*"/>
<tbody>
<row>
<entry>Field</entry>
<entry>Value</entry>
</row>
<row>
<entry>Database Field</entry>
<entry>CART.NUMBER</entry>
</row>
<row>
<entry>Type</entry>
<entry>CART</entry>
</row>
<row>
<entry>Id Data Type</entry>
<entry>Unsigned Integer</entry>
</row>
<row>
<entry>RDNotification::Type Value</entry>
<entry>RDNotification::CartType [1]</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 xml:id="sect.notifications.types.log">
<title>Logs</title>
<table xml:id="table.notifications.types.logs" frame="all" pgwide="0">
<title>Log Fields</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="Field" colwidth="2.0*"/>
<colspec colname="Value" colwidth="2.0*"/>
<tbody>
<row>
<entry>Field</entry>
<entry>Value</entry>
</row>
<row>
<entry>Database Field</entry>
<entry>LOGS.NAME</entry>
</row>
<row>
<entry>Type</entry>
<entry>LOG</entry>
</row>
<row>
<entry>Id Data Type</entry>
<entry>String</entry>
</row>
<row>
<entry>RDNotification::Type Value</entry>
<entry>RDNotification::LogType [2]</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 xml:id="sect.notifications.types.pypad">
<title>Pypad Instances</title>
<table xml:id="table.notifications.types.pypad" frame="all" pgwide="0">
<title>Pypad Instance Fields</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="Field" colwidth="2.0*"/>
<colspec colname="Value" colwidth="2.0*"/>
<tbody>
<row>
<entry>Field</entry>
<entry>Value</entry>
</row>
<row>
<entry>Database Field</entry>
<entry>PYPAD_INSTANCES.ID</entry>
</row>
<row>
<entry>Type</entry>
<entry>PYPAD</entry>
</row>
<row>
<entry>Id Data Type</entry>
<entry>Integer</entry>
</row>
<row>
<entry>RDNotification::Type Value</entry>
<entry>RDNotification::PypadType [3]</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 xml:id="sect.notifications.types.dropbox">
<title>Dropbox Instances</title>
<table xml:id="table.notifications.types.dropbox" frame="all" pgwide="0">
<title>Dropbox Instance Fields</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="Field" colwidth="2.0*"/>
<colspec colname="Value" colwidth="2.0*"/>
<tbody>
<row>
<entry>Field</entry>
<entry>Value</entry>
</row>
<row>
<entry>Database Field</entry>
<entry>DROPBOXES.ID</entry>
</row>
<row>
<entry>Type</entry>
<entry>DROPBOX</entry>
</row>
<row>
<entry>Id Data Type</entry>
<entry>Integer</entry>
</row>
<row>
<entry>RDNotification::Type Value</entry>
<entry>RDNotification::DropboxType [4]</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 xml:id="sect.notifications.types.catch_event">
<title>RDCatch Event Instances</title>
<table xml:id="table.notifications.types.catch_event" frame="all" pgwide="0">
<title>RDCatch Event Fields</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="Field" colwidth="2.0*"/>
<colspec colname="Value" colwidth="2.0*"/>
<tbody>
<row>
<entry>Field</entry>
<entry>Value</entry>
</row>
<row>
<entry>Database Field</entry>
<entry>RECORDINGS.ID</entry>
</row>
<row>
<entry>Type</entry>
<entry>CATCH_EVENT</entry>
</row>
<row>
<entry>Id Data Type</entry>
<entry>Integer</entry>
</row>
<row>
<entry>RDNotification::Type Value</entry>
<entry>RDNotification::CatchEventType [5]</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 xml:id="sect.notifications.types.feed_item">
<title>RSS Feed Items</title>
<table xml:id="table.notifications.types.feed_item" frame="all" pgwide="0">
<title>RSS Feed Item Fields</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="Field" colwidth="2.0*"/>
<colspec colname="Value" colwidth="2.0*"/>
<tbody>
<row>
<entry>Field</entry>
<entry>Value</entry>
</row>
<row>
<entry>Database Field</entry>
<entry>PODCASTS.ID</entry>
</row>
<row>
<entry>Type</entry>
<entry>FEED_ITEM</entry>
</row>
<row>
<entry>Id Data Type</entry>
<entry>Unsigned Integer</entry>
</row>
<row>
<entry>RDNotification::Type Value</entry>
<entry>RDNotification::FeedItemType [6]</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 xml:id="sect.notifications.types.feed">
<title>RSS Feeds</title>
<table xml:id="table.notifications.types.feed" frame="all" pgwide="0">
<title>RSS Feed Fields</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="Field" colwidth="2.0*"/>
<colspec colname="Value" colwidth="2.0*"/>
<tbody>
<row>
<entry>Field</entry>
<entry>Value</entry>
</row>
<row>
<entry>Database Field</entry>
<entry>FEEDS.KEY_NAME</entry>
</row>
<row>
<entry>Type</entry>
<entry>FEED</entry>
</row>
<row>
<entry>Id Data Type</entry>
<entry>String</entry>
</row>
<row>
<entry>RDNotification::Type Value</entry>
<entry>RDNotification::FeedType [7]</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
</sect1>
<sect1 xml:id="sect.rdcatch_messages">
<title>RDCatch Messages</title>
<para>
RDCatch messages use the following format:
</para>
<para>
CATCH <replaceable choice='req'>orig-hostname</replaceable>
<replaceable choice='req'>operation</replaceable>
<replaceable choice='req'>arg1</replaceable>
<replaceable choice='opt'>[...]</replaceable>
</para>
<variablelist>
<varlistentry>
<term>
<replaceable>orig-hostname</replaceable>
</term>
<listitem>
<para>
The name of the host originating the message. From STATIONS.NAME.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<replaceable>operation</replaceable>
</term>
<listitem>
<para>
The RDCatch operation. See the list below.
</para>
</listitem>
</varlistentry>
</variablelist>
<sect2 xml:id="sect.rdcatch_event_processed">
<title>Deck Event Processed Operation</title>
<para>
Emitted by <command>rdcatchd</command><manvolnum>8</manvolnum> every
time a 'Cut Event' ['CE'] RML is processed.
</para>
<table xml:id="table.rdcatch_event_processed" frame="all" pgwide="0">
<title>RDCatch Event Fields</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
<colspec colname="Field" colwidth="10.0*"/>
<colspec colname="Offset" colwidth="2.0*"/>
<colspec colname="Value" colwidth="10.0*"/>
<tbody>
<row>
<entry>Field</entry>
<entry>Offset</entry>
<entry>Value</entry>
</row>
<row>
<entry>Keyword</entry>
<entry>0</entry>
<entry>CATCH</entry>
</row>
<row>
<entry>Originating Hostname</entry>
<entry>1</entry>
<entry>String, from STATIONS.NAME</entry>
</row>
<row>
<entry>Operation</entry>
<entry>2</entry>
<entry>Integer. 1 [RDCatchEvent::DeckEventProcessedOp]</entry>
</row>
<row>
<entry>Deck Channel</entry>
<entry>3</entry>
<entry>
Integer. Record decks have values in the range 1-127,
while play decks have values in the range 128-254.
</entry>
</row>
<row>
<entry>Event Number</entry>
<entry>4</entry>
<entry>
Integer. The value of CUT_EVENTS.NUMBER.
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 xml:id="sect.rdcatch_deck_status">
<title>Deck Status Operation</title>
<para>
Emitted by <command>rdcatch</command><manvolnum>1</manvolnum> at
startup to request the current status of all decks.
</para>
<table xml:id="table.rdcatch_deck_status.request" frame="all" pgwide="0">
<title>RDCatch Event Request Fields</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
<colspec colname="Field" colwidth="10.0*"/>
<colspec colname="Offset" colwidth="2.0*"/>
<colspec colname="Value" colwidth="10.0*"/>
<tbody>
<row>
<entry>Field</entry>
<entry>Offset</entry>
<entry>Value</entry>
</row>
<row>
<entry>Keyword</entry>
<entry>0</entry>
<entry>CATCH</entry>
</row>
<row>
<entry>Originating Hostname</entry>
<entry>1</entry>
<entry>String, from STATIONS.NAME</entry>
</row>
<row>
<entry>Operation</entry>
<entry>2</entry>
<entry>Integer. 2 [RDCatchEvent::DeckStatusQueryOp]</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Emitted by <command>rdcatchd</command><manvolnum>8</manvolnum> whenever
the status of a deck changes, or as a set in response to a request.
(See <xref linkend="table.rdcatch_deck_status.request" />).
</para>
<table xml:id="table.rdcatch_deck_status.response" frame="all" pgwide="0">
<title>RDCatch Event Response Fields</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
<colspec colname="Field" colwidth="10.0*"/>
<colspec colname="Offset" colwidth="2.0*"/>
<colspec colname="Value" colwidth="10.0*"/>
<tbody>
<row>
<entry>Field</entry>
<entry>Offset</entry>
<entry>Value</entry>
</row>
<row>
<entry>Keyword</entry>
<entry>0</entry>
<entry>CATCH</entry>
</row>
<row>
<entry>Originating Hostname</entry>
<entry>1</entry>
<entry>String, from STATIONS.NAME</entry>
</row>
<row>
<entry>Operation</entry>
<entry>2</entry>
<entry>Integer. 3 [RDCatchEvent::DeckStatusResponseOp]</entry>
</row>
<row>
<entry>Deck Channel</entry>
<entry>3</entry>
<entry>
Integer. Record decks have values in the range 1-127,
while play decks have values in the range 128-254.
</entry>
</row>
<row>
<entry>Status</entry>
<entry>4</entry>
<entry>
Integer. Current status of the specified deck. See
<xref linkend="sect.rdcatch_deck_status.deck_status_codes" />
for code point values.
</entry>
</row>
<row>
<entry>Event ID</entry>
<entry>5</entry>
<entry>
Unsigned Integer, from RECORDINGS.ID or 0 if deck is inactive.
</entry>
</row>
<row>
<entry>Cart Number</entry>
<entry>6</entry>
<entry>
Unsigned Integer, from CART.NUMBER or 0 if deck status is not
3 [Active].
</entry>
</row>
<row>
<entry>Cut Number</entry>
<entry>7</entry>
<entry>
Integer, from cut part of CUTS.CUTNAME or 0 if deck status is
not 3 [Active].
</entry>
</row>
</tbody>
</tgroup>
</table>
<sect3 xml:id="sect.rdcatch_deck_status.deck_status_codes">
<title>Deck Status Codes</title>
<table frame="all">
<title>Deck Status Codes</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
<colspec colname="Code" colwidth="1.0*" />
<colspec colname="Meaning" colwidth="5.0*" />
<colspec colname="RDDeck::Status" colwidth="5.0*" />
<thead>
<row>
<entry>Code</entry>
<entry>Meaning</entry>
<entry>RDDeck::Status Value</entry>
</row>
</thead>
<tbody>
<row>
<entry>0</entry>
<entry>Offline</entry>
<entry>RDDeck::Offline</entry>
</row>
<row>
<entry>1</entry>
<entry>Idle</entry>
<entry>RDDeck::Idle</entry>
</row>
<row>
<entry>2</entry>
<entry>Ready</entry>
<entry>RDDeck::Ready</entry>
</row>
<row>
<entry>3</entry>
<entry>Active (playing or recording)</entry>
<entry>RDDeck::Recording</entry>
</row>
<row>
<entry>4</entry>
<entry>Waiting (for a GPI)</entry>
<entry>RDDeck::Waiting</entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2 xml:id="sect.rdcatch_reload_decks">
<title>Reload Decks Operation</title>
<para>
Emitted by <command>rdadmin</command><manvolnum>1</manvolnum> to
trigger a reload of the record and play-out deck parameters.
</para>
<table xml:id="table.rdcatch_reload_decks" frame="all" pgwide="0">
<title>RDCatch Reload Decks Fields</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
<colspec colname="Field" colwidth="10.0*"/>
<colspec colname="Offset" colwidth="2.0*"/>
<colspec colname="Value" colwidth="10.0*"/>
<tbody>
<row>
<entry>Field</entry>
<entry>Offset</entry>
<entry>Value</entry>
</row>
<row>
<entry>Keyword</entry>
<entry>0</entry>
<entry>CATCH</entry>
</row>
<row>
<entry>Originating Hostname</entry>
<entry>1</entry>
<entry>String, from STATIONS.NAME</entry>
</row>
<row>
<entry>Operation</entry>
<entry>2</entry>
<entry>Integer. 7 [RDCatchEvent::ReloadDecksOp]</entry>
</row>
<row>
<entry>Target Hostname</entry>
<entry>3</entry>
<entry>String, from STATIONS.NAME</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 xml:id="sect.rdcatch_send_meter_levels">
<title>Send Meter Levels Operation</title>
<para>
Emitted by <command>rdcatchd</command><manvolnum>8</manvolnum> to
update audio meter levels for active record and play-out decks.
</para>
<table xml:id="table.rdcatch_send_meter_levels" frame="all" pgwide="0">
<title>RDCatch Send Meter Levels Fields</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
<colspec colname="Field" colwidth="10.0*"/>
<colspec colname="Offset" colwidth="2.0*"/>
<colspec colname="Value" colwidth="10.0*"/>
<tbody>
<row>
<entry>Field</entry>
<entry>Offset</entry>
<entry>Value</entry>
</row>
<row>
<entry>Keyword</entry>
<entry>0</entry>
<entry>CATCH</entry>
</row>
<row>
<entry>Originating Hostname</entry>
<entry>1</entry>
<entry>String, from STATIONS.NAME</entry>
</row>
<row>
<entry>Operation</entry>
<entry>2</entry>
<entry>Integer. 8 [RDCatchEvent::SendMeterLevelsOp]</entry>
</row>
<row>
<entry>Meter Entry</entry>
<entry>3</entry>
<entry>String, <replaceable>chan</replaceable>:<replaceable>left-lvl</replaceable>:<replaceable>right-lvl</replaceable></entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 xml:id="sect.rdcatch_set_input_monitor">
<title>Set Input Monitor</title>
<para>
Emitted by <command>rdcatch</command><manvolnum>1</manvolnum> to
turn a deck input monitor on or off.
</para>
<table xml:id="table.rdcatch_set_input_monitor" frame="all" pgwide="0">
<title>RDCatch Set Input Monitor Fields</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
<colspec colname="Field" colwidth="10.0*"/>
<colspec colname="Offset" colwidth="2.0*"/>
<colspec colname="Value" colwidth="10.0*"/>
<tbody>
<row>
<entry>Field</entry>
<entry>Offset</entry>
<entry>Value</entry>
</row>
<row>
<entry>Keyword</entry>
<entry>0</entry>
<entry>CATCH</entry>
</row>
<row>
<entry>Originating Hostname</entry>
<entry>1</entry>
<entry>String, from STATIONS.NAME</entry>
</row>
<row>
<entry>Operation</entry>
<entry>2</entry>
<entry>Integer. 5 [RDCatchEvent::SetInputMonitorOp]</entry>
</row>
<row>
<entry>Target Hostname</entry>
<entry>3</entry>
<entry>String, from STATIONS.NAME</entry>
</row>
<row>
<entry>Deck Channel</entry>
<entry>4</entry>
<entry>
Integer. Record decks have values in the range 1-127,
while play decks have values in the range 128-254.
</entry>
</row>
<row>
<entry>State</entry>
<entry>5</entry>
<entry>
Boolean. 0=False, 1=True.
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 xml:id="sect.rdcatch_set_input_monitor_response">
<title>Set Input Monitor Response</title>
<para>
Emitted by <command>rdcatchd</command><manvolnum>8</manvolnum> to
signal change of a deck input monitor.
</para>
<table xml:id="table.rdcatch_set_input_monitor_response" frame="all" pgwide="0">
<title>RDCatch Set Input Monitor Fields</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
<colspec colname="Field" colwidth="10.0*"/>
<colspec colname="Offset" colwidth="2.0*"/>
<colspec colname="Value" colwidth="10.0*"/>
<tbody>
<row>
<entry>Field</entry>
<entry>Offset</entry>
<entry>Value</entry>
</row>
<row>
<entry>Keyword</entry>
<entry>0</entry>
<entry>CATCH</entry>
</row>
<row>
<entry>Originating Hostname</entry>
<entry>1</entry>
<entry>String, from STATIONS.NAME</entry>
</row>
<row>
<entry>Operation</entry>
<entry>2</entry>
<entry>Integer. 6 [RDCatchEvent::SetInputMonitorResponseOp]</entry>
</row>
<row>
<entry>Deck Channel</entry>
<entry>3</entry>
<entry>
Integer. Record decks have values in the range 1-127,
while play decks have values in the range 128-254.
</entry>
</row>
<row>
<entry>State</entry>
<entry>4</entry>
<entry>
Boolean. 0=False, 1=True.
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 xml:id="sect.rdcatch_stop_deck">
<title>Stop Deck Operation</title>
<para>
Emitted by <command>rdcatch</command><manvolnum>1</manvolnum> to
abort a Record or Play-out event.
</para>
<table xml:id="table.rdcatch_stop_deck" frame="all" pgwide="0">
<title>RDCatch Stop Deck Fields</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
<colspec colname="Field" colwidth="10.0*"/>
<colspec colname="Offset" colwidth="2.0*"/>
<colspec colname="Value" colwidth="10.0*"/>
<tbody>
<row>
<entry>Field</entry>
<entry>Offset</entry>
<entry>Value</entry>
</row>
<row>
<entry>Keyword</entry>
<entry>0</entry>
<entry>CATCH</entry>
</row>
<row>
<entry>Originating Hostname</entry>
<entry>1</entry>
<entry>String, from STATIONS.NAME</entry>
</row>
<row>
<entry>Operation</entry>
<entry>2</entry>
<entry>Integer. 4 [RDCatchEvent::StopDeckOp]</entry>
</row>
<row>
<entry>Target Hostname</entry>
<entry>3</entry>
<entry>String, from STATIONS.NAME</entry>
</row>
<row>
<entry>Deck Channel</entry>
<entry>4</entry>
<entry>
Integer. Record decks have values in the range 1-127,
while play decks have values in the range 128-254.
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
</sect1>
</article>
Reference in New Issue View Git Blame Copy Permalink