Internet DRAFT - draft-padgen-webradio
draft-padgen-webradio
INTERNET-DRAFT Neil Padgen
Category: Experimental BBC Monitoring
<draft-padgen-webradio-00.txt> 16 December 1999
Expires: 13 June 2000
A Web-Controlled Radio Broadcast Receiving and Monitoring System
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet- Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
Status of this Memo
This memo defines an Experimental Protocol for the Internet
community. This memo does not specify an Internet standard of any
kind. Discussion and suggestions for improvement are requested.
Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (1999). All Rights Reserved.
Abstract
Organisations such as BBC Monitoring monitor radio and television
broadcasts worldwide. Traditional monitoring methods incur expensive
international telephone call charges. This document describes a
system whereby remote broadcasts can be monitored using a computer
connected to a radio or television receiver and to the Internet,
using inexpensive local calls to its local Internet Service Provider.
This document also defines the protocol used between the central
server and the remote clients which implement this system.
Padgen Experimental [Page 1]
INTERNET-DRAFT A Web-Controlled Radio System March 1999
1. Introduction
The proliferation of radio and television broadcasting in recent
years has significantly increased the importance of monitored media
as a prime source of breaking news and current affairs.
Organisations such as BBC Monitoring draw upon radio, television and
news agency reports from many sources worldwide. Bulletins are
monitored, then some local processing (such as translation into
English) is performed on the monitored broadcast.
Traditional methods of monitoring remote broadcasts have involved
installing a receiver at the remote site, and contacting that
receiver using standard telephone lines. This incurs expensive
international call charges.
This document describes a system where the equipment installed at the
remote site consists of a computer connected to a receiver, and with
a modem to connect to the local Internet Service Provider (ISP).
This enables broadcasts to be recorded on the remote computer, then
uploaded to a central server for the cost of a short local telephone
call.
This document defines the protocol to be used between the central
server and the remote clients which implement this system.
2. Structure
The web-controlled receiver system ("web radio system") consists of
one central machine (known as the "server") and a number of remote
machines (known as the "clients"). All user interaction takes place
with the server.
The arrangement of the server and clients is something like the
following:
Padgen Experimental [Page 2]
INTERNET-DRAFT A Web-Controlled Radio System March 1999
+----------------+
| | +-------+
| server |------| modem |
| | +-------+
+----------------+
| server's network
-------------------------------------------
|
----------------------
( )
+-------( Internet )------+
| ( ) |
: ---------------------- :
: : :
: : :
| | |
| | |
+-------+ +-------+ +-------+
| modem | | modem | | modem |
+-------+ +-------+ +-------+
| | |
+----------+ +----------+ +----------+
| webradio | | webradio | .... | webradio |
| client 1 | | client 2 | | client N |--------+
+----------+ +----------+ +----------+ |
| | | |
+----------+ +----------+ +------------+ +------------+
| receiver | | receiver | | receiver 1 | ... | receiver M |
+----------+ +----------+ +------------+ +------------+
The server has a permanent connection to the Internet. It also has
access to a modem, although this will rarely be used.
This document will detail the protocol used between the client and
the server. Details of the implementation of the web radio system
are not discussed here.
3. Notational Conventions and Generic Grammar
3.1. Notational Conventions
This specification uses the same words as RFC 1123[1] for defining
the significance of each particular requirement. These words are:
MUST
This word or the adjective "required" means that the item is an
absolute requirement of the specification.
Padgen Experimental [Page 3]
INTERNET-DRAFT A Web-Controlled Radio System March 1999
SHOULD
This word or the adjective "recommended" means that there may exist
valid reasons in particular circumstances to ignore this item, but
the full implications should be understood and the case carefully
weighed before choosing a different course.
MAY
This word or the adjective "optional" means that this item is truly
optional. One vendor may choose to include the item because a
particular marketplace requires it or because it enhances the
product, for example; another vendor may omit the same item.
An implementation is not compliant if it fails to satisfy one or more
of the MUST requirements for the protocols it implements. An
implementation that satisfies all the MUST and all the SHOULD
requirements for its protocols is said to be "unconditionally
compliant"; one that satisfies all the MUST requirements but not all
the SHOULD requirements for its protocols is said to be
"conditionally compliant."
3.2. Augmented BNF
All of the mechanisms specified in this document are described in
both prose and an augmented Backus-Naur Form (BNF) similar to that
used by RFC 822[2]. Implementers will need to be familiar with the
notation in order to understand this specification. The augmented
BNF includes the following constructs:
name = definition
The name of a rule is simply the name itself (without any enclosing
"<" and ">") and is separated from its definition by the equal "="
character. Whitespace is only significant in that indentation of
continuation lines is used to indicate a rule definition that spans
more than one line. Certain basic rules are in uppercase, such as
SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle brackets are used
within definitions whenever their presence will facilitate
discerning the use of rule names.
"literal"
Quotation marks surround literal text. Unless stated otherwise,
the text is case-insensitive.
rule1 | rule2
Elements separated by a bar ("|") are alternatives, e.g., "yes |
no" will accept yes or no.
Padgen Experimental [Page 4]
INTERNET-DRAFT A Web-Controlled Radio System March 1999
(rule1 rule2)
Elements enclosed in parentheses are treated as a single element.
Thus, "(elem (foo | bar) elem)" allows the token sequences "elem
foo elem" and "elem bar elem".
*rule
The character "*" preceding an element indicates repetition. The
full form is "<n>*<m>element" indicating at least <n> and at most
<m> occurrences of element. Default values are 0 and infinity so
that "*(element)" allows any number, including zero; "1*element"
requires at least one; and "1*2element" allows one or two.
[rule]
Square brackets enclose optional elements; "[foo bar]" is
equivalent to "*1(foo bar)".
; comment
A semi-colon, set off some distance to the right of rule text,
starts a comment that continues to the end of line. This is a
simple way of including useful notes in parallel with the
specifications.
3.3. Basic Rules
The following rules are used throughout this specification to
describe basic parsing constructs. The US-ASCII coded character set
is defined by ANSI X3.4-1986[3].
OCTET = <any 8-bit sequence of data>
CHAR = <any US-ASCII character (octets 0 - 127)>
UPALPHA = <any US-ASCII uppercase letter "A".."Z">
LOALPHA = <any US-ASCII lowercase letter "a".."z">
ALPHA = UPALPHA | LOALPHA
DIGIT = <any US-ASCII digit "0".."9">
CTL = <any US-ASCII control character
(octets 0 - 31) and DEL (127)>
CR = <US-ASCII CR, carriage return (13)>
LF = <US-ASCII LF, linefeed (10)>
SP = <US-ASCII SP, space (32)>
HT = <US-ASCII HT, horizontal-tab (9)>
<"> = <US-ASCII double-quote mark (34)>
The TEXT rule is only used for descriptive field contents and values
that are not intended to be interpreted by the message parser.
TEXT = <any OCTET except CTLs>
Padgen Experimental [Page 5]
INTERNET-DRAFT A Web-Controlled Radio System March 1999
The backslash character ("\") may be used as a single-character
quoting mechanism within all constructs.
quoted-pair = "\" CHAR
4. Client-server communication
4.1. Underlying protocol
The underlying protocol used between the client and server is
HTTP[4]. A client contacts the server by sending an HTTP POST
request, consisting of the data as detailed below. The server's
response is formatted with a MIME type of text/plain.
This protocol was chosen in the event that a client's ISP only allows
HTTP and FTP[5] traffic to be passed through. It also allows
underlying HTTP security features (as described in [4, 6] ) to be
used to authenticate the client, rather than reinventing the wheel by
developing a new security protocol specifically for this system.
4.2. Format of a client request
A client's request is an HTTP POST request with the following
parameters defined:
o HOST - the name of the client, as the server understands it. This
need not be the Internet name or address of the client. Suggested
client names might detail the physical location (city and country)
of the client.
o REQUEST - the web radio function being requested. The set of
requests which MUST be implemented are detailed below.
o DATA - any extra data needed for this request. This is not
required for every request, but requests which do require
additional data have the details below.
o VERSION - the version of the protocol. This document describes
version 1.0. If the VERSION parameter is missing, version 1.0 is
assumed.
4.3. Client requests and server responses
A list of permissible requests and responses follows. In the
examples given in this section, the client is known as "Remote
Padgen Experimental [Page 6]
INTERNET-DRAFT A Web-Controlled Radio System March 1999
client".
The requests listed in this section MUST be implemented by both
client and server. Extensions to the protocol MAY be formed by
submitting a request formatted in a similar way to those that follow,
with the mandatory HOST and REQUEST parameters and optional DATA
parameter.
If an error occurs in processing a client request, the server MUST
replace the expected response with an error-response. Similarly, if
the server does not implement a request from a client which is not in
the protocol as specified here, an error-response MUST be returned.
An error-response takes the following form:
error-response = "ERROR: " error-message
error-message = <any TEXT>
4.3.1. The "send_stations" request
The server responds with a list of all stations known for this
client. The response consists of a number of lines, each of which is
the definition of a station.
send_stations-response = *( station-definition CR )
station-definition = station-name ":"
station-frequency ":"
station-band
station-name = <any TEXT excluding ":"
except as quoted-pair>
station-frequency = *DIGIT "." *DIGIT ; MUST be at least
; one DIGIT in the
; station-frequency
station-band = 1*( [ ALPHA | DIGIT ] )
The station-name is a descriptive name of the station. It MUST be
unique within this list.
The station-frequency is a numeric field indicating the frequency in
MHz.
The station-band is an alphanumeric field indicating the radio band
Padgen Experimental [Page 7]
INTERNET-DRAFT A Web-Controlled Radio System March 1999
to use. For example, AM or WFM.
Example:
The client sends:
HOST=Remote client
VERSION=1.0
REQUEST=send_stations
The server responds:
BBC Radio 1:99.4:WFM
BBC Radio 4 FM:94.2:WFM
BBC Radio 4 LW:.198:AM
4.3.2. The "send_queue" request
The server responds with a list of jobs with which the client should
update its queue. This response MUST contain at a minimum all jobs
which have changed status since the client last sent a "queue_update"
request.
The response consists of a number of lines, each of which is a job-
definition.
send_queue-response = *( job-definition CR )
job-definition = job-number ":"
start-time ":"
duration ":"
station-name ":"
notify-address ":"
status
job-number = 1*( DIGIT )
start-time = 1*( DIGIT )
duration = 1*( DIGIT )
notify-address = <RFC822-formatted mail address>
; any ":" in this
; field MUST be escaped
; as a quoted-pair
job-status = numeric-job-status
Padgen Experimental [Page 8]
INTERNET-DRAFT A Web-Controlled Radio System March 1999
[ ( " " job-status-comment ) ]
job-status-character = 3*( DIGIT )
job-status-comment = <any TEXT excluding ":"
except as quoted-pair>
The job-number is a numeric field which acts as the key for this job.
It MUST be unique within the queue.
The start-time indicates the time at which the job is due to start.
It is given in Unix time; i.e. seconds since Jan 1, 1970.
The duration gives the amount of time that the job is to last. It is
given in seconds.
The station-name indicates which station the radio should be tuned
to. It MUST correspond to a station in the station_list response.
The notify_address is an Internet address to which mail MAY be sent
indicating the progress of the job.
The job-status indicates the status of the job. The optional job-
status-comment MAY contain a description of the status, e.g. an error
message.
The numeric-job-status consists of three digits, each of which has a
different meaning. These are as follows:
4.3.2.1. First digit of numeric-job-status
1 - indicates that the job is scheduled.
2 - indicates that the job has been deleted.
3 - indicates that the job has been successfully completed.
4 - indicates that the job is in progress.
5 - indicates that the job has been successfully recorded, but that
the recording has not yet been uploaded; when a status of this
type is indicated, the job-status-comment MUST be present and
indicate, in Unix time, the earliest possible time at which the
recording might be uploaded.
6 - MAY be used to indicate an implementation-dependent status; when
a status of this type is indicated, the job-status-comment MUST
Padgen Experimental [Page 9]
INTERNET-DRAFT A Web-Controlled Radio System March 1999
be present and indicate details of the status.
9 - indicates that an error has occurred; when a status of this type
is indicated, the job-status-comment MUST be present and indicate
details of the status.
4.3.2.2. Second digit of numeric-job-status
1 - indicates that only the client knows that the job has the status
indicated in the first digit of numeric-job-status.
2 - indicates that only the server knows that the job has the status
indicated in the first digit of numeric-job-status.
3 - indicates that both the client and server know that the job has
the status indicated in the first digit of numeric-job-status.
4.3.2.3. Third digit of numeric-job-status
1 - indicates that a recording is to be made of this job.
2 - indicates that this job is to be served live.
3 - indicates that this job is both to be served live, and a
recording is to be made.
Note that nothing prohibits a recording being made of a job whose
third status digit is 2, nor is live serving of a job whose third
status digit is 1 prohibited. In other words, an implementation MAY
both serve live and record all jobs, for example.
Example:
The client sends:
HOST=Remote client
VERSION=1.0
REQUEST=send_queue
The server responds:
1:910872300:1800:BBC Radio 4 FM:user@domain.com:221 Job deleted
3:910874100:1800:BBC Radio 4 FM:user@domain.com:121 New job
Padgen Experimental [Page 10]
INTERNET-DRAFT A Web-Controlled Radio System March 1999
4.3.3. The "queue_update" request
This request requires a DATA parameter to be present in the request.
The client sends the server a list of jobs. This MUST include at a
minimum jobs which have changed status since the last time a
"queue_update" request was sent by the client.
The DATA parameter is a single line consisting of queue_update-data.
queue_update-data = queue_update-pair
*( ":" queue_update_pair )
queue_update-pair = job-number ":"
queue_update-status
queue_update-status = ( "OK"
| ( "ERROR " reason )
| ( "COMPLETE " [file] )
| ( "STREAM " url )
)
reason = <any TEXT excluding ":"
except as quoted-pair>
file = <any TEXT excluding ":"
except as quoted-pair>
url = <a valid URL, with any ":"
as quoted-pair>
The queue_update-status takes one of the following forms:
OK The queue update, as sent from the server in
response to a "send_queue" request, was processed
successfully.
ERROR reason There was an error processing this job. The
reason gives details of the error.
COMPLETE file The job has completed. If a recording was
specified, the file indicates where the
recording can be found.
STREAM url The job is currently being streamed live.
The url indicates how the live stream may
be received.
Padgen Experimental [Page 11]
INTERNET-DRAFT A Web-Controlled Radio System March 1999
DELAY time Recording of the job has finished, but uploading
of the recording to the server has been delayed
until at least the time (in Unix time) given.
The server responds with a single line:
queue_update-response = "OK"
Example:
Following the example given in the "send_queue" request above, the
client processes the job updates. The deletion of job 1 is fine, but
the new job 3 overlaps with an existing scheduled job.
The client sends:
HOST=Remote client
VERSION=1.0
REQUEST=queue_update
DATA=1:OK:3:ERROR Job 2 already scheduled at that time
The server responds:
OK
4.3.4. The "receivers" request
This request requires a DATA parameter to be present in the request.
The client indicates to the server how many receivers are attached to
it. The DATA parameter is a single line consisting of receivers-
data.
receivers-data = 1*( DIGIT )
The server responds with a single line:
receivers-response = "OK"
This function can help with scheduling, since overlapping jobs can be
scheduled when more than one receiver is present on a client. When a
user submits a new schedule, the server MAY check immediately that
this scheduling does not conflict with existing schedules.
Example:
The client sends:
Padgen Experimental [Page 12]
INTERNET-DRAFT A Web-Controlled Radio System March 1999
HOST=Remote client
VERSION=1.0
REQUEST=receivers
DATA=1
The server responds
OK
and notes that this client has one receiver attached.
4.3.5. The "next_check" request
This request requires a DATA parameter to be present in the request.
The client indicates to the server when it can next be expected to
check its queue by sending a "send_queue" request. The DATA
parameter is a single line consisting of next_check-data.
next_check-data = 1*( DIGIT )
The next_check-data is the time (given in Unix time) that the next
check will take place.
The server responds with a single line:
next_check-response = "OK"
This function allows the server to know if a client will
automatically check to pick up a job scheduled at short notice, and
to dial the client directly to force a check if this is not the case.
Example:
The client sends:
HOST=Remote client
VERSION=1.0
REQUEST=next_check
DATA=918216000
The server responds
OK
and notes that the client will next check its queue on Fri Feb 5
12:00:00 GMT 1999.
Padgen Experimental [Page 13]
INTERNET-DRAFT A Web-Controlled Radio System March 1999
5. Security Considerations
There is no provision in this protocol for access control. Rather,
access SHOULD be controlled using one of the access authentication
schemes available for HTTP (see [4, 6] for details.)
6. Notes
A system using this protocol has been developed by the author. A
number of web radio clients are being installed at various locations
around the world.
Although this document refers solely to receiving radio broadcasts,
there is nothing in the protocol to limit monitoring to audio-only.
For example, a client may control a television receiver and be able
to record video from this receiver. The same protocol could be used,
without modification, to control this client.
7. References
[1] Braden, R., "Requirements for Internet hosts - application and
support," STD 3, RFC 1123 (October 1989).
[2] Crocker, D., "Standard for the Format of ARPA Internet Text
Messages"," STD 11, RFC 822 (August 1982).
[3] ANSI, "US-ASCII. Coded Character Set - 7-Bit American Standard
Code for Information Interchange.," Standard ANSI X3.4-1986,
ANSI (1986).
[4] Fielding, R., Irvine, U.C., Gettys, J., Mogul, J., Frystyk, H.,
and Berners-Lee, T., "Hypertext Transfer Protocol -- HTTP/1.1,"
RFC 2068 (January 1997).
[5] Postel, J. and Reynolds, J., "FILE TRANSFER PROTOCOL (FTP)," STD
9, RFC 959 (October 1985).
[6] Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P.,
Luotonen, A., Sink, E., and Stewart, L., "An Extension to HTTP :
Digest Access Authentication," RFC 2069 (January 1997).
8. Author's Address
Neil Padgen
BBC Monitoring
Padgen Experimental [Page 14]
INTERNET-DRAFT A Web-Controlled Radio System March 1999
Caversham Park
Reading RG4 8TZ
United Kingdom
Tel: +44 7971 165 865
Email: nrp@i.am
9. Acknowledgement
This document has been published with the permission of BBC
Monitoring. Address:
IT Department
BBC Monitoring
Caversham Park
Reading RG4 8TZ
United Kingdom
10. Full Copyright Statement Notice
Copyright (C) The Internet Society (1999). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Padgen Experimental [Page 15]
INTERNET-DRAFT A Web-Controlled Radio System March 1999
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Structure . . . . . . . . . . . . . . . . . . . . . . . . . 2
3. Notational Conventions and Generic Grammar . . . . . . . . . 3
3.1. Notational Conventions . . . . . . . . . . . . . . . . . . . 3
3.2. Augmented BNF . . . . . . . . . . . . . . . . . . . . . . . 4
3.3. Basic Rules . . . . . . . . . . . . . . . . . . . . . . . . 5
4. Client-server communication . . . . . . . . . . . . . . . . 6
4.1. Underlying protocol . . . . . . . . . . . . . . . . . . . . 6
4.2. Format of a client request . . . . . . . . . . . . . . . . . 6
4.3. Client requests and server responses . . . . . . . . . . . . 6
4.3.1. The "send_stations" request . . . . . . . . . . . . . . . . 7
4.3.2. The "send_queue" request . . . . . . . . . . . . . . . . . . 8
4.3.3. The "queue_update" request . . . . . . . . . . . . . . . . . 10
4.3.4. The "receivers" request . . . . . . . . . . . . . . . . . . 12
4.3.5. The "next_check" request . . . . . . . . . . . . . . . . . . 13
5. Security Considerations . . . . . . . . . . . . . . . . . . 14
6. Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
8. Author's Address . . . . . . . . . . . . . . . . . . . . . . 14
9. Acknowledgement . . . . . . . . . . . . . . . . . . . . . . 15
10. Full Copyright Statement Notice . . . . . . . . . . . . . . 15
Padgen Experimental [Page 16]
