$Id: controls.txt 2575 2012-02-20 03:04:31Z isely $ The following list describes known information about each control available in the driver's sysfs interface. Some items are known because the driver directly implements them. Other items are not so well known, being that they get passed directly to the hardware and it is up to the hardware to act on their meaning. **** NOTE: Many of these control names and functions have changed due to the transition to the new mpeg API and the cx2341x module in later kernels. This needs to be updated. Results of experimenting with various settings ctl_audio_bitrate: 384kb/s OK 320kb/s OK 256kb/s OK 224kb/s OK <--- default 192kb/s OK 160kb/s stuttering 128kb/s stuttering 112kb/s stuttering, sync issues 96kb/s severe stuttering 80kb/s nothing but skips 64kb/s max headroom syndrome 56kb/s severe stuttering, picture seizes 48kb/s severe stuttering, picture seizes 32kb/s no audio, slideshow VBR no datastream at all, apparently This is the compressed physical bit rate in the stream. This corresponds to the MP3 encoding rate. The underlying logical bit rate is determined by ctl_srate. ctl_audio_crc - This is on by default. Turning it off doesn't seem to break anything, but I could not notice any difference in mplayer at all (probably because not having audio crcs is not a big deal). Otherwise, no idea what this does. ctl_audio_emphasis - Default is "None". Other values don't seem to have any ill effects. Possibly this may change audio quality, but using mplayer with a cheap motherboard audio chip and mid-grade PC speakers, I don't hear any difference. ctl_audio_layer: 0 mplayer freezes when detecting audio, video data present 1 mplayer freezes when detecting audio, video data present 2 OK (canonical mp3 format apparently) <-- default 3 mplayer freezes when detecting audio, video data present No idea what this really does. ctl_audio_mode - Default is Stereo. Intended for controlling audio program choice, e.g. "Stereo", "Mono", "SAP". Unfortunately for NTSC folks it appears not to work, due to problems in msp3400.ko. With NTSC there are two audio standard choices and msp3400.ko has to switch between them. This is only the case for NTSC, not any other standard. Unfortunately msp3400.ko (at least the versions I have looked at) doesn't handle this correctly and thus you can't select SAP (can't really tell if Mono is working at all since it sounds approximately the same). There is more information in the driver's FAQ about this issue. ctl_balance - Input of any value will not have any effect if the underlying msp34xx variant in the device doesn't support this function (and my device seems not to support it). ctl_bass - Same problem(s) as ctl_balance. ctl_brightness - Video brightness. ctl_channel - This is part of the internal frequency table management. If this is set to a non-zero value, then that corresponding channel's frequency is set as the frequency to tune. You can read this back at any time to see what channel has been tuned by this logic. If at any time ctl_frequency is directly set, then the notion of "current channel" is erased and you'll read back a zero here. Note: This feature has nothing to do with any application's idea of channel - an application is free to do its own channel management and to program frequencies directly. This is usually the case; V4L doesn't implicitly see this part of the driver. ctl_contrast - Video contrast. ctl_debug_subsys_mask - This is a bit mask showing what parts of the driver are enabled at any given moment. When streaming starts / stops, various subsystems have to be stopped / started in the correct order. This is a debugging aid. Don't mess with it unless you know what you are doing. ctl_debug_subsys_stream_mask - This is a bit mask showing exactly which subsystems are enabled / disabled when streaming is enabled / disabled. This is a debugging aid. Don't mess with it unless you know what you are doing. ctl_freq_table_channel - This is part of the internal frequency table management. Set this to select a channel to examine or change. Channel must be an integer. This works in concert with ctl_freq_table_value. Note: The driver's notion of a frequency table is COMPLETELY independent of V4L. This is only present to help with non-V4L situations. You do not need to program channels; you can just write to ctl_frequency directly. ctl_freq_table_value - This is part of the internal frequency table management. Set this to program a frequency for the currently selected channel (selected by ctl_freq_table_channel) or read it to see what the current frequency is for the given channel. ctl_frequency - Works fine (default is US Broadcast channel 7). Note that this value is expressed in Hz. ctl_hue - Video hue. ctl_input: television OK s-video OK composite OK radio kills driver (safely) Select input source on the device. Note: Radio support does not yet exist in the driver. Attempting to set up the radio input is not exactly a good idea right now. ctl_interlace - Default is 0 (for NTSC). Setting it to 1 appears to cut the vertical resolution in half and overall picture quality degrades significantly (even beyond that which one would expect from losing half the vertical resolution). No real idea what this control really should be doing. Note: This value may get silently reset when changing the video standard. ctl_mute - Works fine (default is off). Note: Some apps like to mute the audio on exit (e.g. xawtv), and other apps have no idea about mute (e.g. mplayer) because they must treat the driver as just a file. This can cause confusion when for example you stop xawtv and then start mplayer. Check this setting and fix it before asking for help. ctl_resolution_hor - Default is 720 (for NTSC). Selects horizontal frame resolution. Entire range (320-720) seems to work just fine. Note: This value may get silently reset when changing the video standard. ctl_resolution_ver - Default is 480 (for NTSC). Selects vertical frame resolution. Any value above 480 seems to corrupt the video display (as if the vertical sync pulse were in the wrong place). 480 is a reasonable limit for NTSC, probably (hopefully) for video standards with greater vertical resolution this effective limit may be higher. Note: This value may get silently reset when changing the video standard. ctl_saturation - Video saturation, also known as "color" control on some televisions. ctl_signal_present - This is a read only integer value, and reports strength of the received signal. Zero means no signal, any other value suggests the presence of a signal up to a value of 65535 for maximum strength. The granularity and accuracy of this value depends on the underlying v4l chip-level drivers which report this value to the pvrusb2 driver. For example a driver might only ever report 0 or 65535. This status value also seems to work for composite & s-video input in additional to television and radio. Older versions of the driver (up to the in-kernel 2.6.20 version) instead reported a boolean value here. Now we attempt to report actual signal strength. ctl_srate - Default is 48KHz. Alternate setting is 44.1KHz. Works perfectly. This selects the underlying logical sample rate for the audio stream. ctl_streaming_enabled - This is a read only boolean value which is true any time data streaming has been enabled. ctl_treble - Same problem(s) as ctl_balance. ctl_usb_speed - This is a read only enumerated value which reports the connection speed of the device. Normally this should be "High", unless you connected using a USB 1.1 host adapter or hub somewhere in the USB datapath. Note: While it's possible to make a single PVR USB2 work this way, there isn't enough bandwidth at "Full" speed to multiplex more than one PVR USB2 on the same USB connection. (You'll probably get video breakup and corruption.) ctl_vbr - Default value is zero. Probably enable VBR encoding of video stream, however I can't be sure. There is no effect of this setting at all if the average and peak video rates are the same. However if the peak rate is higher, then mplayer reports the "rate" to be the peak rate if this is off, and reports the "rate" to be the average rate if this is on. It's possible that with this on that the average rate is indeed the requested average, but can vary up to the peak rate. But I can't really tell if this is happening. ctl_video_average_bitrate - Seems to work perfectly, but watch out that you don't set this to be greater than the peak rate (ctl_video_peak_bitrate). With encoder firmware from the older(!!) pvrusb2_23_31351 driver package, this situation seems to be correctly handled by the hardware (rate capped to the actual peak rate). With all other driver packages however the result is corrupted video. This seems to be the setting for the desired video stream bit rate. ctl_video_peak_bitrate - Seems to work perfectly This seems to be a setting for setting the maximum video stream bit rate. The actual bit rate at any given time seems to the result of this setting, the average bit rate setting, and the vbr setting. ctl_video_standard - This enumeration value corresponds to the video standard currently set in the driver. The default value corresponds to the supported standard as detected in the hardware, so in the USA this typically will default to NTSC-M, but in other places the default might be different. If the PVR USB2 device is a multi-standard tuner, then one choice will be arbitrarily chosen as the default. You can examine this to see what standard is in effect, or change it to adjust the device and the driver to the desired standard. NOTE: This control goes away starting some time after the 3.0 kernel series. Why? Because internal driver changes remove the need for directly managing this enumeration. Instead, core V4L logic now synthesizes this internally where needed, but that's all inside V4L and no longer visible to the pvrusb2 driver. However the same effects can be controlled via ctl_video_standard_mask_active (in fact, the V4L core derives its operation from this other control). ctl_video_standard_mask_active - This is a bit mask that shows exactly which video standard settings are currently active. Usually only a single bit should ever be set (exceptions: B/G and D/K combinations). Note that while ctl_video_standard is an enumeration (that is made available to the app through a normal V4L ioctl), internally everyone speaks in terms of a bit mask; this control is the actual bit mask. The operation of this control and ctl_video_standard are reasonably synchronized; changing one will correspondingly affect the other. After roughly kernel 3.0, ctl_video_standard in fact goes away and control is instead handled just through here. ctl_video_standard_mask_available - This is a bit mask that shows exactly which video standard settings are supported by the hardware, as reported / determined during driver initialization. This value is normally determined by the particular hardware PVR USB2 device you have connected. The bits set here will drive the calculations involving the other video standard related controls. The bits set here are initialized based on what tveeprom reports as being supportable in the hardware, among other things. You can change this mask, if you suspect your hardware supports a standard not already set - but you normally should never have to do this. ctl_video_standard_mask_detected - This is a bit mask that shows exactly which video standard settings are currently actually available, based on hardware present and the run-time detection logic of various parts of the hardware and related driver pieces. This is normally always going to be a subset of ctl_video_standard_mask_available. The difference between "available" and "detected" is that "available" should be limited to what the hardware can actually do while "detected" also theoretically takes into account what signals might be getting received. Internally this subset is calculated by core V4L logic, not this driver. It may very well show the same value as "available". Note that since this is calculated internally, it is strictly read-only, while "available" can be set (as a means to try to forcibly expand the list of available standards). This control didn't exceed until drivers after roughly Jan 2012 for the standalone driver and likely not until 3.4.x for in-kernel drivers. ctl_volume - This is the volume setting for the audio part of the tuner. Note that this only affects the television input; volume level for all other inputs is currently fixed.