Autres/Rivendellaudio
1
0
Fork 0
mirror of https://github.com/ElvishArtisan/rivendell.git synced 2025-04-09 22:43:11 +02:00
Code Issues Projects Releases Wiki Activity

2019-03-28 Fred Gleason <fredg@paravelsystems.com>

Browse Source 
* Added a 'Program Associated Data' chapter to the Operations
	Guide.
This commit is contained in:
Fred Gleason 2019-03-29 18:45:10 -04:00
parent 871d93a08f
commit 72294a3325
5 changed files with 272 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
ChangeLog
View File

@ -18555,3 +18555,6 @@
* Added a startup check for the 'rivendell' service.
2019-03-22 Fred Gleason <fredg@paravelsystems.com>
* Incremented the package version to 3.0.0rc00.
2019-03-28 Fred Gleason <fredg@paravelsystems.com>
* Added a 'Program Associated Data' chapter to the Operations
Guide.

4
docs/opsguide/Makefile.am
View File

@ -2,7 +2,7 @@
##
## docs/opsguide/automake.am for Rivendell
##
## (C) Copyright 2017 Fred Gleason <fredg@paravelsystems.com>
## (C) Copyright 2017-2019 Fred Gleason <fredg@paravelsystems.com>
##
## This program is free software; you can redistribute it and/or modify
## it under the terms of the GNU General Public License version 2 as
@ -26,6 +26,7 @@ OPSGUIDE_HTML = appendix.filepath_wildcards.html\
appendix.rivendell_filter.html\
appendix.wings_filter.html\
chapter.overview.html\
chapter.pad.html\
chapter.rdadmin.html\
chapter.rdairplay.html\
chapter.rdcartslots.html\
@ -282,6 +283,7 @@ OPSGUIDE_DEPS = $(OPSGUIDE_IMAGES) \
opsguide.xml\
overview.xml\
metadata_wildcards.xml\
pad.xml\
rdadmin.xml\
rdairplay.xml\
rdcartslots.xml\

2
docs/opsguide/opsguide.xml
View File

@ -2,6 +2,7 @@
<!DOCTYPE book [
<!ENTITY frontspiece SYSTEM "frontspiece.xml">
<!ENTITY pad SYSTEM "pad.xml">
<!ENTITY overview SYSTEM "overview.xml">
<!ENTITY rdlogin SYSTEM "rdlogin.xml">
<!ENTITY rdlibrary SYSTEM "rdlibrary.xml">
@ -40,6 +41,7 @@
<title>Rivendell Administration</title>
&rdadmin;
&rml;
&pad;
&utilities;
</part>
<part xml:id="part.appendices" xmlns="http://docbook.org/ns/docbook" version="5.0">

194
docs/opsguide/pad.xml Normal file
View File

@ -0,0 +1,194 @@
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="chapter.pad">
<title>Program Associated Data</title>
<sect1 xml:id="sect.pad.overview">
<title>Overview</title>
<para>
Rivendell includes full support for the origination and transmission
of program associated data (PAD) in realtime, including a Python
module (PyPAD)
that can be used to create scripts for interfacing Rivendell's PAD
feed to most any arbitrary external system.
</para>
<sect2 xml:id="sect.pad.the_json_interface">
<title>The JSON Interface</title>
<para>
All Rivendell PAD updates are emitted as
<link xlink:href="https://www.json.org/">JSON documents</link> of
type <code>padUpdate</code> via TCP port 34289. A typical update
looks like:
<programlisting>
<![CDATA[
{
"padUpdate": {
"dateTime": "2019-03-28T15:09:01-04:00",
"hostName": "elastigirl",
"shortHostName": "elastigirl",
"machine": 1,
"onairFlag": false,
"mode": "Automatic",
"service": {
"name": "Production",
"description": "Production Log"
"programCode": ""
},
"log": {
"name": "Example"
},
"now": {
"startDateTime": "2019-03-28T15:09:01-04:00",
"lineNumber": 0,
"lineId": 0,
"cartNumber": 10477,
"cartType": "Audio",
"cutNumber": 1,
"length": 225500,
"year": null,
"groupName": "MUSIC",
"title": "Allentown",
"artist": "Billy Joel",
"publisher": "",
"composer": "",
"album": "The Complete Hits Collection 1973-1997",
"label": "",
"client": "",
"agency": "",
"conductor": "",
"userDefined": "",
"songId": "",
"outcue": "",
"description": "Cut 001",
"isrc": "",
"isci": "",
"externalEventId": "",
"externalData": "",
"externalAnncType": ""
},
"next": {
"startDateTime": "2019-03-28T15:12:46-04:00",
"lineNumber": 1,
"lineId": 1,
"cartNumber": 10153,
"cartType": "Audio",
"cutNumber": 1,
"length": 168700,
"year": null,
"groupName": "MUSIC",
"title": "Me & You & A Dog Named Boo",
"artist": "Lobo",
"publisher": "",
"composer": "",
"album": "'70s Radio Hits",
"label": "",
"client": "",
"agency": "",
"conductor": "",
"userDefined": "",
"songId": "",
"outcue": "",
"description": "Cut 001",
"isrc": "",
"isci": "",
"externalEventId": "",
"externalData": "",
"externalAnncType": ""
}
}
}]]>
</programlisting>
</para>
</sect2>
<sect2 xml:id="sect.pad.pypad">
<title>PyPAD</title>
<para>
Rivendell ships with a Python 3 module called &quot;pypad&quot; that
automates away most of the work involved in reading, parsing and
processing the raw JSON data feed described above. A copiously
commented example script can be found in the Rivendell source
tree at <userinput>apis/pypad/tests/now_and_next.py</userinput>.
</para>
<sect3 xml:id="sect.pad.pypad.starting_scripts_sutomatically_with_the_rivendell_service">
<title>Starting Scripts Automatically with the &quot;rivendell&quot; Service</title>
<para>
Rivendell can be configured to start one or more PyPAD scripts
automatically whenever the &quot;rivendell&quot; systemd service
is (re)started. In order to support this, a PyPAD script must
meet the following requirements:
</para>
<itemizedlist>
<listitem>
<para>
Accept exactly three command-line arguments as follows:
</para>
<para>
<userinput>script <replaceable>host-name</replaceable>
<replaceable>port-num</replaceable>
<replaceable>config</replaceable></userinput>
</para>
<para>
The <replaceable>config</replaceable> value should be
passed to the <code>pypad.Receiver.setConfigFile()</code> method,
and <replaceable>host-name</replaceable> and
<replaceable>port-num</replaceable> values should be
passed to the
<code>pypad.Receiver().start()</code> method.
See any of the production PyPAD scripts in the Rivendell
sources in <userinput>apis/pypad/scripts/</userinput> for
an example.
</para>
</listitem>
<listitem>
<para>
If the script is configurable via a configuration file,
provide a sample copy of the configuration file, using
wherever possible sane
default values along with comments documenting
what the various parameters do. The file should have the
the same base name as that of the script, but have an
<userinput>.exemplar</userinput> extension.
</para>
<para>
For example, if the script is called
<userinput>myscript.py</userinput>,
the sample configuration file would be called
<userinput>myscript.exemplar</userinput>.
</para>
</listitem>
<listitem>
<para>
Install a copy of the script, along with a copy of the
sample configuration file (if needed) in the Rivendell
PyPAD script directory
<userinput><replaceable>$(libdir)</replaceable>/rivendell/pypad/</userinput>.
</para>
<note>
In the RHEL/CentOS reference installation, this directory
is <userinput>/usr/lib64/rivendell/pypad/</userinput>.
</note>
<note>
The <userinput><replaceable>$(libdir)</replaceable></userinput>
path component evaluates to
the value used for the <userinput>--libdir</userinput>
switch that was passed to the &quot;configure&quot; script
when Rivendell was built [default value:
<userinput>/usr/local/lib</userinput>].
</note>
</listitem>
</itemizedlist>
<para>
All PyPAD scripts started in this manner will be run under the
user/group specified by the <userinput>PypadOwner=</userinput>
and <userinput>PypadGroup=</userinput> directives in the
<userinput>[Identity]</userinput> section of the
<command>rd.conf</command><manvolnum>5</manvolnum> configuration
file.
</para>
<para>
See <xref linkend="sect.rdadmin.managing_pypad_instances" />
for instructions on enabling a script that has been
prepared in this manner.
</para>
</sect3>
</sect2>
</sect1>
</chapter>

72
docs/opsguide/rdadmin.xml
View File

@ -2206,7 +2206,14 @@
PyPAD is a system that is built into Rivendell that
allows processing and transmission of Program Associated Data [PAD]
by means of scripts written in the popular Python programming
language. To see the list of PyPAD scripts configured to run on
language.
</para>
<note>
See <xref linkend="sect.pad.pypad" /> for information
on creating your own customized PyPAD scripts.
</note>
<para>
To see the list of PyPAD scripts configured to run on
the selected host, touch the
<computeroutput>PyPAD Instances</computeroutput> button to open
the PyPAD Instances dialog.
@ -2260,8 +2267,69 @@
<para>
When finished editing the configuration, touch the
<computeroutput>OK</computeroutput> button to save the configuration
and start the script running.
and start the script running. The green light adjacent to the entry
for the script instance just edited will turn red briefly before
turning back to green, indicating that the changes to the configuration
have been applied to the active instance.
</para>
<note>
It is not necessary to restart rdairplay(1) for the configuration
changes to be made effective.
</note>
<sect3 xml:id="sect.rdadmin.moving_legacy_rlm_configurations_to_pypad">
<title>Moving Legacy RLM Configurations to PyPAD</title>
<para>
Rivendell v2.x included a feature called &quot;Rivendell Loadable
Modules&quot; (&quot;RLM&quot; for short) that included much of
the functionality now provided by PyPAD. The following RLMs that
shipped as part of Rivendell v2.x have been ported to PyPAD
and shipped as part of Rivendell 3.x:
</para>
<simplelist>
<member><computeroutput>rlm_ando</computeroutput></member>
<member><computeroutput>rlm_filewrite</computeroutput></member>
<member><computeroutput>rlm_icecast2</computeroutput></member>
<member><computeroutput>rlm_inno712</computeroutput></member>
<member><computeroutput>rlm_liqcomp</computeroutput></member>
<member><computeroutput>rlm_live365</computeroutput></member>
<member><computeroutput>rlm_serial</computeroutput></member>
<member><computeroutput>rlm_shoutcast1</computeroutput></member>
<member><computeroutput>rlm_spottrap</computeroutput></member>
<member><computeroutput>rlm_tunein</computeroutput></member>
<member><computeroutput>rlm_udp</computeroutput></member>
<member><computeroutput>rlm_urlwrite</computeroutput></member>
<member><computeroutput>rlm_walltime</computeroutput></member>
<member><computeroutput>rlm_xds</computeroutput></member>
<member><computeroutput>rlm_xmpad</computeroutput></member>
</simplelist>
<para>
The formats of the configuration files used for these plug-ins are
unchanged under PyPAD. Thus, a &quot;known good&quot; configuration
file for an RLM can simply be copy/pasted into the
<computeroutput>Configuration</computeroutput> box in the
<computeroutput>Edit PyPAD Instance</computeroutput> dialog
when setting up its replacement PyPAD script.
</para>
<caution>
Be sure to remove completely the default &quot;sample&quot;
configuration entries before copy/pasting in the
&quot;known good&quot; ones!
</caution>
<sect4 xml:id="sect.rdadmin.moving_a_spinitron_rlm_configuration_to_pypad">
<title>Moving a Spinitron RLM Configuration to PyPAD</title>
<para>
In addition to the above, some of the functionality of the
<computeroutput>rlm_spinitron_plus</computeroutput> RLM has
been ported into the
<computeroutput>pypad_spinitron</computeroutput> script.
Specifically, support for the deprecated Spinitron v1 interface
has been removed. Sites which have not yet transitioned to
Spinitron v2 will need to do so in order to use this script.
Sites which are already using Spinitron v2 can use their existing
RLM configuration unchanged.
</para>
</sect4>
</sect3>
</sect2>
</sect1>
<sect1 xml:id="sect.rdadmin.manage_system_settings">