radio_xmit(6) (man pages section 6: Demos)

man pages section 6: Demos

radio_xmit(6)

NAME

radio_xmit– radio broadcast utility

SYNOPSIS

radio_xmit [ -C ]  [OPTION=value ] ...

DISCLAIMER

This program is furnished on an AS IS basis as a demonstration of audio applications programming.

DESCRIPTION

radio_xmit is the Radio Free Ethernet (RFE) broadcast utility. (For an overview of Radio Free Ethernet, refer to the radio(6) manual page.) Though radio_xmit is normally initiated directly by the window-based xmit(6) program, it may also be used directly as a command-line program, or in conjunction with a user-written window-based tool.

In Normal Mode (the default case), radio_xmit is initiated with a set of broadcast options specified on the command line. The program immediately begins transmitting audio data over the network according to the currently selected options. The program will terminate on receipt of a SIGINT (CTRL-C). If an input file is specified, the program will exit when the entire file has been broadcast.

If -C is specified on the command line, radio_xmit operates in Command Mode. In this mode, the program reads and processes command options from stdin and writes error and status information to stderr. Window-based tools use Command Mode to control the broadcast program and receive status information for display. When operating in Command Mode, radio_xmit requires that a station name and input file be specified explicitly, and the START command must be issued to initiate broadcasting.

OPTIONS

The broadcast options are described below. If an option requires a value, the option name must be followed by an equal sign (=) and the value. If an option takes an ON/OFF value, the default is ON if the value is missing or poorly constructed.

Station=[call letters]

This option specifies the station call letters of your radio station. A maximum of four characters may be specified. In Normal Mode, the station name defaults to the first four letters of the current workstation hostname. However, it is preferable to supply a Station name on the command line.

Input=[audio file or device name]

This option specifies the audio input source for radio broadcast. If a file is specified, it must be a legitimate audio file (i.e., with a standard Sun audio file header), sampled at 8 kHz. In Normal Mode, the audio input defaults to /dev/audio.

Squelch=[ON/OFF]

This option controls the behavior of the transmitter when the audio input data is determined to be silent. When Squelch is enabled, silent data is not transmitted over the network. This reduces the network traffic for stations that are broadcasting with no audio input. Note that the Station Identification packet continues to be transmitted every 5 seconds, even if the data broadcast is squelched.

When Squelch is disabled, all audio input data is always transmitted. Squelching only occurs for audio device input; audio files are not squelched, even if they contain silence. The Squelch option is enabled by default.

Format=[COMPRESSED/UNCOMPRESSED]

This option controls the format for audio data that is broadcast. The uncompressed format broadcasts 8000 bytes of audio data each second. The compressed format sends only 4000 bytes per second, but requires more computation on both the transmitter and receiver.

Data format conversions only occur for audio device input; audio files are transmitted in the format in which they were stored. By default, audio data is broadcast uncompressed.

Agc=[ON/OFF]

This option controls the behavior of an Automatic Gain Control feature. When Agc is enabled, the audio recording volume is adjusted automatically to keep the input signal within reasonable bounds. If the input signal is too loud, the record volume is decreased. If the input signal is determined to be present but too soft, the record volume is increased.

Automatic Gain Control adjustments only occur for audio device input; audio files are broadcasted at the level at which they were recorded. The Agc option is enabled by default.

Autostop=[ON/OFF]

This option controls the behavior of the transmitter when the audio input data has been silent for a length of time. When Autostop is enabled, the transmitter will sign off the station and stop broadcasting if the audio input has been silent for 60 seconds. When Autostop is disabled, the station continues to remain active. This option does not interact with the Squelch option, although the same criteria are used for determining whether or not the audio input is silent.

Autostop is only processed for audio device input; broadcasting always stops when an end-of-file has been reached on audio files. The Autostop option is disabled by default.

Address=[hostname|address]

This option is used to configure the IP Multicast base address that the radio_xmit program uses for broadcasting data. The value may either be a hostname (which is translated into an IP Multicast address by looking up the name in the NIS hosts map) or a specific numeric IP Multicast address.

Normally, the address should end in 0 or 255, in which case an id-address and data-address are constructed as follows: the id-address consists of the address with the last byte set to 255; the data-address consists of the base address with a randomly-selected last byte (0-254). Station identification packets are broadcast to the id-address, and normal audio data packets are broadcast to the data-address. This convention allows RFE receivers to register interest only in the id-address, so that audio data packets need not be replicated over network gateways until a receiver actually tunes in to the station.

If the IP Multicast address ends in a byte that is in the range 1-254, then the address remains unmodified, and both station and identification packets are broadcast to that address. This convention allows a specific multicast address to be used for multi-party audio conferences.

The default IP Multicast address is designated by the hostname RadioFreeEthernet. The special hostname BROADCAST may be used to force the program to transmit UDP Broadcast packets (which will not be relayed over a network gateway). The radio(6) manual page contains more information on the RFE network implementation.

Range=[hopcount]

This option is used to configure the number of gateways over which a radio broadcast may pass. If the value is set to one, the broadcast will be restricted to the current subnet. The default Range is 8.

Service=[service|port number]

This option is used to configure the IP protocol port number used to identify Radio Free Ethernet network packets. The value may be either a service name (which is translated into a port number by looking up the name in the NIS services map) or a specific numeric port number.

The default port number is designated by the service name radio. The radio(6) manual page contains more information on configuring the port number.

Report=[ON/OFF]

This option enables the reporting, to stderr, of all changes in the transmitter status. It is normally used only in conjunction with Command Mode to allow the controlling program to maintain state.

Buffer=[input buffer size in bytes]

In normal operation, the RFE tools are not concerned with the delay between the audio input at the transmitter and the output of audio data at the receiving end. Following the model of radio broadcasting, the delay is not important as long as the transmitted data arrives in sequence and on time. For this reason, and to ensure a consistent, uninterrupted flow of audio data, the radio_xmit program normally uses a buffer size of around 8000 bytes to collect audio input data before broadcasting. This results in an end-to-end delay of approximately one second (or longer if the receiver's audio buffer backs up).

For use with real-time audio conferencing, shorter delays may be desired. For experimental purposes, the Buffer command is provided to alter the input delay. The buffer size is specified in bytes. For real-time experimentation, a reasonable value is 256 (corresponding to approximately 1/32 of a second). Notice that a side-effect of lowering the input buffer size is to lower the transmitted packet size, resulting in an increased number of broadcast packets.

Start

This command is used to initiate broadcasting according to the current parameter settings. It is provided for Command Mode; the transmitter is enabled by default in Normal Mode.

Stop

This command is used to sign off the current station and cease broadcasting. It is provided for Command Mode operation.

Quit

This command causes the radio_xmit program to exit. It is provided for Command Mode operation.

EXAMPLES

Example 1 Broadcasting over a network

Let's say that you have a radio at work that you always keep tuned to your favorite station (though you might shut off your speakers when you don't want to listen to it). If you connect its output to your workstation audio input, you can broadcast the station over the network by using the following command (the Autostop option will cause the program to sign-off and exit if you turn your radio off for a minute or longer):

example% radio_xmit Station=KPFA Input=/dev/audio Autostop=on

Example 2 Rescheduling a broadcast

The following shell script may be scheduled to run every day at 6:00 AM to record a half-hour of news and rebroadcast it at a more sensible time:

#!/bin/sh
# Record from /dev/audio for 30 minutes (around 14 Mbytes).
file=/bigdisk/sound/news
audiorecord -t 30:00 $file
#
# If this runs at 6am, the news is over at 6:30.  Wait 3 hours til 9:30.
sleep 10800
#
# Now broadcast the news on the network and remove the file when finished.
radio_xmit Station=KPFA Input=$file
rm $file