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

man pages section 6: Demos

radio_recv(6)

NAME

radio_recv– radio receive utility

SYNOPSIS

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

DISCLAIMER

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

DESCRIPTION

radio_recv is the Radio Free Ethernet (RFE) receiver. (For an overview of Radio Free Ethernet, refer to the radio(6) manual page.) Though radio_recv is normally initiated directly by the window-based radio(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_recv is initiated with a set of receiver options specified on the command line. The program immediately begins scanning the network for radio broadcasts according to the currently selected options. The program will terminate on receipt of a SIGINT (CTRL-C). Once the receiver tunes in a broadcasting station, the program will exit when the station signs off.

If -C is specified on the command line, radio_recv 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 receiver program and receive status information for display. When operating in Command Mode, radio_recv requires that an output device be specified explicitly, and the START command must be issued to initiate radio reception.

OPTIONS

The receiver 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 a radio station to tune in. A maximum of four characters may be specified. If the receiver is enabled without specifying a station, the receiver will tune in the first station that is transmitting audio data.

Output=[audio device name]

This option specifies the audio output device. In Normal Mode, the audio output defaults to /dev/audio.

Release=[ON/OFF]

When the receiver tunes in a radio station, it assumes exclusive control of the audio output device. If another process attempts to claim the audio device for output, it will fail (or suspend until the device is released). In such cases, the radio_recv program may be notified that another process is competing for the audio output channel.

If the Release option is enabled, the receiver will automatically release the audio device when such notification occurs, allowing other processes the opportunity to claim the device. As long as the device remains unavailable, the receiver will throw away any radio broadcast packets that are detected. When the device is available again, the receiver will reclaim it and continue playing the incoming audio data. If the Release option is disabled, radio_recv will maintain exclusive control of the audio device until it is explicitly stopped or the incoming radio station signs off.

The Release option is enabled by default.

Address=[hostname|address]

This option is used to configure the IP Multicast address that the radio_recv program uses to locate radio broadcasts. 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. The special hostname BROADCAST may be used to force the program to scan only for UDP Broadcast packets.

The default IP Multicast address is designated by the hostname RadioFreeEthernet. The radio(6) manual page contains more information on the IP Multicast implementation.

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 receiver status. This option also enables the reporting of the active station list. The station list details the state of all active radio stations, and is output whenever a state change is observed. The Report option is normally used only in conjunction with Command Mode to allow the controlling program to maintain state.

Scan

This command is used to initiate scanning for a new radio station. The receiver tunes in to the next radio station whose broadcast is detected. When multiple stations are actively broadcasting, the scan cycles through them all before repeating a station. Note that stations whose broadcast is being squelched due to a silent input signal are not tuned in.

Start

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

Stop

This command is used to turn off the receiver. Queued audio data is flushed so that audio output stops immediately. The Stop command is provided for the Command Mode operation.

Quit

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