Capture Application

The cx88 package includes a simple capture application, which is (at least currently) also called 'cx88'--really creative naming, right? :) This app uses a multithreaded architecture in which a data source thread is spawned for each cx88 device to handle device configuration and to wait for wait for data buffers to be filled by the driver. The application includes a modular capture architecture that allows an arbitrary number of capture feeds to be created, each running in its own thread. A list of capture feeds is registered with each data source thread, and as buffers become available, the data source threads submit them to the capture feeds for further processing. For example, a single MPEG TS data source thread may be associated with a UDP capture feed and two file capture feeds, allowing the captured MPEG video to be simultaneously streamed live over a UDP socket and stored in two separate files. The main application thread is responsible for processing interactive input commands from the user or a remote control connection (see below).

Usage

The capture app recognizes the following options:

-d <device name> : Specifies the device node under /dev from which data should be captured. At least one -d directive must be specified. Multiple -d directives may be specified if multiple capture streams are necessary; for example, when capturing both raw video and audio.

-x <filename> : Specifies the XML channel configuration file that should be used. If this option is omitted, the application will attempt to use ~/.cx88.xml.

-c <string> : Specifies the channel to from which to start capturing. The channel name should follow the channel naming rules of the XML configuration file (see below). If this option is omitted, the default channel from the XML configuration file is used.

-u <URL> : Specifies a destination URL to which captured data should be sent. The following URL formats are currently supported:

-t <filename> : Specifies a libtuner configuration file for use with the current device. Libtuner configuration is typically specified in the XML channel configuration file, but this option may be used to provide additional configuration options. These options should be in the same newline-delimited <key>=<value> format as the libtuner section of the XML file. Note that, like the -u option, this option applies only to the current device.

-o <string> : Allows custom options to be supplied to the capture thread for the current device. The option string should be in the form of <key>=<value>;<key>=<value>;... --in other words, a semicolon-delimited version of the libtuner configuration format. In fact, libtuner configuration settings may be supplied using this option. Beyond any libtuner configuration settings, the following settings are currently recognized by the application:

Key

Default Value

Comments

packet_delay

100

Specifies the number of packets to discard at the beginning of a capture or after a channel change. Applies only to MPEG TS devices. Depending on the tuner, the first few packets can have invalid payloads, which can cause problems for some decoders.

buffer

4,194,304 (4MB)

For file captures, specifies the amount of data (in bytes) that should be cached before being flushed to the file--this can prevent excessive disk access during long-duration captures

mtu

1500

For UDP/TCP captures, specifies the maximum transmission unit for the socket

pip

For analog video captures, specifies the cx88video device that should be used for the secondary (smaller) picture in a picture-in-picture capture

-n <number> : Specify a time limit, in minutes, for the duration of the capture. This value may not be a whole number, for example '0.1' can be used to specify a 6-second capture. This is intended to be the maximum duration for a capture from a single channel, so changing the channel will reset the timer.

-p <number> : Specify a port on which to listen for remote control commands (see below). If this option is omitted, the remote control interface will be disabled.

-q : Specifies that the application will not listen to stdin for interactive commands. This can be useful when running the application in batch environments (such as a job scheduled by cron(8) or at(1)), where interactive control is not needed and the behavior of stdin is undefined. This option must be used in conjunction with the -p and/or the -n option.

-h : Specify that the application is to start in the "halted" state, in which data capture will not start automatically. The capture must be started by issuing the 'h' command either interactively or via the remote control interface.

-l <number> : Specify the maximum duration (in milliseconds) to apply when waiting for the tuner to lock to a channel. The default is 1000.

Interactive Control

When the cx88 application is invoked without the '-q' option, the user may enter several commands on the terminal to control it. Each command consists of a single character, followed by <ENTER>. The commands The following commands are supported:

c : Change the channel. After entering this command, you will be prompted for the name of the channel. The channel name must following the naming rules of the XML configuration file (see below). Additionally, the keywords 'first' and 'last' may be used to specify the lowest and highest channel number in the current profile, respectively. The keywords 'up' and 'down' may be used to navigate through a list of channels. If the current channel was selected using a channel number, then the 'up' and 'down' keywords will navigate through the current profile. If the current channel was selected using an alias defined in the XML file, then the 'up' and 'down' keywords will navigate through the list of channel presets defined by the aliases in the XML file.

i : Display signal information. The information content varies depending upon whether a digital or analog capture is being peformed, and upon the types of information that the frontend supports. For digital channels, this will typically include at least the signal strength, and for analog channels it will include video broadcast system and audio subcarrier information.

h : Toggle the 'halted' state of the driver; that is, start or stop capture.

s : Scan for valid channels in the current channel profile (defined by the XML file). After entering this command, you will be prompted for a minimum signal strength threshold (as a percentage). The output of the scan will list the number and signal strength percentage of each valid channel with a signal strength greater than or equal to the specified threshold.

q : Terminate the application.

Remote Control Interface

If the '-p' option is specified, then the application will listen for TCP connections on the provided port. Only one connection is allowed at a time. The remote application can then control the cx88 app by sending sending command strings as sequences of characters. The command strings should begin with one of interactive command characters listed above, and should be immediately followed by any parameters. For example, the command to change the channel to USA:54 would be "cUSA:54". The command strings should be terminated by the NULL character.

XML Configuration File

The capture app uses an XML configuration file to store channel and tuner configuration information in a hierarchical format. A sample file is installed to /usr/local/share/examples/cx88/cx88.xml.sample. The body of the XML file is denoted by the <cx88> tag. Within this tag, there can be two types of child entities:

  1. At most one "config" entity, denoted by the <config> tag. Within the config entity, there can be the following child entites:

    1. At most one "libtuner" entity, denoted by the <libtuner> tag. This entity should contain a series of libtuner configuration entries, in the standard "key=value" format, with explicit XML linebreaks (</br>) between each entry. This allows the libtuner configuration to be embedded directly in the cx88 config file without requiring an external libtuner config file.

    2. Any number of "alias" entities, denoted by the <alias> tag. This entity defines a string that can be used to reference a numeric channel, and must have two properties:

      1. name: The name to be used for the channel
      2. channel: The numeric channel, either as a pure number (in which case the default profile will be assumed), or as a string of the form "profile_name:number"

    3. At most one "default" entity, denoted by the <default> tag. This entity defines the channel number or alias that will be selected when the application is started.