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:

-a : For audio devices only. Specifies that the capture app will be controlling the audio DMA stream ("normal mode"), instead of a separate OSS-compliant application ("OSS mode"). Implied if any -u options are specified. Can be toggled on-the-fly w/ 'a' command.

-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. 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.

-r <filename> : File name to use when performing a temporary recording (See below). If this option is unspecified, the default is /tmp/cx88.rec

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 follow 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.

c <channel> : Identical to command above, but allows you to specify the channel name on the same line as the 'c' command, without prompting for the name.

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.

s <threshold> : Same as above command, but allows you to specify signal strength threshold on the same line as the 's' command, without prompting for the threshold.

a : Audio devices only. Dynamically switches between normal and OSS capture modes (See above).

v <volume> : Audio devices only. Specifies volume, as a percentage. May be a single number [0-100], or a <left>:<right> pair. Not supported on all hardware.

m : Audio devices only. Mutes the audio volume. Not supported on all hardware.

p : MPEG devices only. Disables MPEG PSI (Program Specific Information) parsing.

+ <url> : Dynamically add a capture with the specified URL

- <number> : Dynamically remove the capture with the specified number. Use 'i' command to list capture URLs and associated capture numbers.

r : Toggles recording state. When enabled, raw data will be saved to a file. By default this file is /tmp/cx88.rec, but this may be overridden with the -r command-line option.

n : Display a list of available input sources for the device. This list is device-specific, but common sources include "tuner" and "line-in" for analog audio, and "tuner", "composite", and "s-video" for analog video.

n <source> : Switch input to the specified source. The source name must be valid for your device, and is not case-sensitive.

? : Display help for available commands and capture URLs.

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. Up to eight simultaneous connections are allowed. The remote application can then control the cx88 app by sending sending command strings in the same format used in interactive mode. Any output generated by the command, including error messages and warnings, will be returned across the same TCP connection.

XML Configuration File

The capture app uses an XML configuration file to store channel and tuner configuration information in a hierarchical format. Ezxml is used to parse the file. 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". To specify a DTV subchannel, the channel number may optionally be suffixed with a dash (-) followed by a program number, e.g. "USA:46-3". While the channel number is typically specified as an integer, you may also use a decimal floating-point value. This is typically useful only for FM radio channels that are named for their frequency in MHz.

    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.

  2. At least one "profile" entity, denoted by the <profile> tag. Each of these entities defines a collection of channels with common properties, typically the set of channels that are available in a particular geographical region. The first profile entity will be considered the default profile. Channel numbers may be prefixed with a profile name and a colon (:). If a channel number is not so prefixed, it is assumed to belong to the default profile. The profile entity must have one property, "name". The following child entities are allowed:

    1. At most one of each of the following signal property entities:

      1. <modulation>: Defines the modulation to be used for digital channels. Valid values are:

        1. "OFDM" : Typically used by DVB-T broadcasts
        2. "QAM" : Quadrature Amplitude Modulation, with the number of constellation points automatically determined by the tuner. Often used in digital cable broadcasts
        3. "QAM16"
        4. "QAM32"
        5. "QAM64"
        6. "QAM128"
        7. "QAM256"
        8. "QPSK" : Often used in satellite broadcasts
        9. "VSB16"
        10. "VSB8" : Used by terrestrial ATSC broadcasts.

      2. <bandwidth>: Channel bandwidth, in Hz. Typically 6000000, 7000000, or 8000000.

      3. <inversion>: Specifies spectral inversion for the digital tuner--valid values are "on", "off", and "auto". The default value is "auto".

      4. <sub_modulation>: For OFDM signals, specifies the subcarrier modulation, which may be any of the values listed above for <modulation>. If this is omitted, the tuner frontend attempt to automatically determine subcarrier modulation.

      5. <symbol_rate>: For QAM and QPSK signals, specifies the symbol rate as an integer value.

      6. <code_rate>: For QAM and QPSK signals, specifies the forward error correction code rate, and may be one of the following values (default is "auto"):

        1. "auto"
        2. "none"
        3. "1/2"
        4. "2/3"
        5. "3/4"
        6. "4/5"
        7. "5/6"
        8. "6/7"
        9. "7/8"
        10. "8/9"

      7. <hp_code_rate>: For OFDM signals, specifies the high-priority FEC code rate, and may be any of the values listed above for <code_rate>.

      8. <lp_code_rate>: For OFDM signals, specifies the low-priority FEC code rate, and may be any of the values listed above for <code_rate>.

      9. <subcarriers>: For OFDM signals, specifies the subcarrier mode, and may be one of the following (default is "auto"):

        1. "auto"
        2. "2k"
        3. "4k"
        4. "8k"

      10. <guard_interval>: For OFDM signals, specifies the guard interval as a fraction of the symbol period (default is "auto"):

        1. "auto"
        2. "1/4"
        3. "1/8"
        4. "1/16"
        5. "1/32"

      11. <hierarchy>: For OFDM signals, specifies the number of hierarchy levels (default is "auto"):

        1. "auto"
        2. "none"
        3. 1
        4. 2
        5. 4

      12. <analog_video>: Specifies the video broadcast format that should be used for analog channels (default is "none"):

        1. "none"
        2. "NTSC-443"
        3. "NTSC-M"
        4. "NTSC-M-Jp"
        5. "NTSC-N"
        6. "PAL-60"
        7. "PAL-B"
        8. "PAL-D"
        9. "PAL-D1"
        10. "PAL-G"
        11. "PAL-H"
        12. "PAL-I"
        13. "PAL-K"
        14. "PAL-M"
        15. "PAL-N"
        16. "PAL-Nc"
        17. "SECAM-B"
        18. "SECAM-D"
        19. "SECAM-G"
        20. "SECAM-H"
        21. "SECAM-K"
        22. "SECAM-K1"
        23. "SECAM-L"
        24. "SECAM-Lc"

      13. <analog_audio>: Specifies the audio broadcast format that should be used for analog channels (default is "none"):

        1. "none"
        2. "A2"
        3. "A2-SAP"
        4. "AM-Mono"
        5. "AM-Stereo"
        6. "BTSC"
        7. "BTSC-SAP"
        8. "EIAJ"
        9. "EIAJ-SAP"
        10. "FM-Mono"
        11. "FM-Mono-50" : Monaural FM w/ 50-ns deemphasis
        12. "FM-Mono-75" : Monaural FM w/ 75-ns deemphasis
        13. "FM-Stereo"
        14. "FM-Stereo-50" : Stereo FM w/ 50-ns deemphasis
        15. "FM-Stereo-75" : Stereo FM w/ 75-ns deemphasis
        16. "NICAM"
        17. "NICAM-SAP"

    2. At least one <range> entity. A range defines a channel or sequence of channels within a profile. The following child entities are allowed:

      1. At most one of each of the signal property entities listed above. Any such entity defined within a <range> will be scoped by the range. If the corresponding entity is also defined in the encompassing <profile>, this entity will override it while the current <range> is in use.

      2. Exactly one of each of the following entities:

        1. <start>: Specifies the starting channel number of the range, as an integer or floating-point value.

        2. <end>: Specifies the ending channel number of the range, as an integer or floating-point value. The range will include all integers in the range from <start> to <end>, inclusive.

        3. <freq>: Specifies the frequency of the first channel in the range, in Hz. This value should correspond to the middle of the channel's frequency spectrum. Subsequent channel frequencies in the range will be offset from this frequency by the value specified in the applicable <bandwidth> entity.

      3. Optionally, exactly one of the following entities:

        1. <step>: The numeric interval between each channel number in the range, as an integer or floating point value. If omitted, the default value is 1.

Sample File

A sample XML config file is installed to /usr/local/share/examples/cx88/cx88.xml.sample. This file may be used directly with the capture app, or you may modify it to fit the broadcast profile in your area. It contains profiles for the USA (w/ digital and analog channel settings), for the EU (VHF and UHF, currently digital settings only), and France (currently digital settings only). Note that the default profile is USA and the channel aliases are configured for the area in which I live (Austin, TX), so unless you also live there you'll probably want to change some things :)

Overview/CaptureApp (last edited 2012-06-25 22:57:02 by jason)