INTERNET-DRAFT Neil Padgen Category: Experimental BBC Monitoring 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 "*element" indicating at least and at most 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 = CHAR = UPALPHA = LOALPHA = ALPHA = UPALPHA | LOALPHA DIGIT = CTL = CR = LF = SP = HT = <"> = The TEXT rule is only used for descriptive field contents and values that are not intended to be interpreted by the message parser. TEXT = 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 = 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 = 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 = ; 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 = 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 = file = url = 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]