tvtime

Articles on using tvtime

  1. Configuring tvtime for displaying XMLTV listings
  2. Configuring lirc for tvtime

General tvtime usage

  1. Setting up tvtime
  2. Deinterlacing modes explained
  3. Using widescreen 16:9 mode
  4. Key bindings
  5. Setting up your channel list in tvtime
  6. The tvtime.xml config file
  7. Controlling tvtime via the tvtime-command

1. Setting up tvtime

Almost all features of tvtime can be configured through the menu system. Click the right mouse button, or hit tab when you run tvtime to bring up the menu. As well, many features can be configured using the command-line tool tvtime-configure. Run 'tvtime-configure --help' to get a list of command line arguments. Make sure tvtime is not running while you use tvtime-configure. An example of using this tool to configure tvtime is given below:

     tvtime-configure --norm=pal --frequencies=europe

This will save to your config file the norm PAL and frequency table Europe as your defaults. See docs/default.tvtime.xml for a default configuration file and the default runtime keybindings.

2. Deinterlacing modes explained

tvtime includes different deinterlacing modes for different types of content as well as different output refresh rates or CPU constraints. Below we have separated out our modes based on their content, and provide a description of each.

Modes for video content

Most of the deinterlacing methods in tvtime are intended for use on video content. All of the following are considered video content:

  • News shows and information channels.
  • Most live-action television dramas.
  • Sports broadcasts.
  • Most video gaming consoles.

We provide three classes of video deinterlacers: Television, Blur and Motion adaptive.

Television mode, full and half resolution

In television mode, tvtime expands each field to full resolution, without ever blurring in time or copying in time. this effectively simulates a television. Use this mode when you want TV-quality with low CPU, and you have configured your monitor to run at the refresh rate of the video signal (59.94 Hz or 50 Hz). There are two television deinterlacers:

  • Full Resolution: High quality for fullscreen use.
  • Half Resolution: Poor quality for watching TV in a small window.

Blur mode, temporal and vertical

In blur mode, tvtime avoids flicker by blurring together consecutive frames of input. Use this if you want to run your monitor at an arbitrary refresh rate, and have tvtime not use much CPU. There are two blur modes available:

  • Vertical: Blur vertically more than temporally, better for high motion content like sports.
  • Temporal: Evenly blur in time, low CPU mode for less flicker, but visible trails on fast motion.

Motion adaptive modes, search, advanced and simple detection

The motion adaptive modes in tvtime try to detect motion in the input frames, reconstructing detail where possible. You want to run your monitor at an arbitrary refresh rate, and don't mind using a lot of CPU. There are three modes available in tvtime:

  • Simple and Advanced detection: Linear interpolation where motion is detected, copy where no motion. Simple and advanced versions are provided to give small or moderate CPU requirements with high quality output. These are the greedy low motion and high motion deinterlacers from DScaler.
  • Motion search: Follow motion vectors for more accurate interpolation. High quality with high CPU requirements. This is the TomsMoComp deinterlacer from DScaler.

Modes built for film content

We are still working on better support for film detection modes in tvtime, but we already support some useful features. Film content is what we would call anything that either originated from film or has been converted to video from an originally progressive format.

  • Films broadcast on TV or from a DVD player.
  • Cartoons and most anime.
  • Some higher budget television dramas
  • Older video gaming consoles.

Progressive (top or bottom field first)

In progressive mode, tvtime constructs frames from pairs of fields. Use this mode if you are using a video game from a console system which sends a progressive signal, or are watching a film broadcast or DVD in a PAL area. There are two modes available:

  • Top Field First and Bottom Field first. You must experiment with your content and see how it is being sent, and select the appropriate mode in tvtime to match it.

Progressive Detection

While not currently available in tvtime, this option would allow us to detect progressive content, and whether it is top or bottom field first, rather than manually setting this option. This would be able to autodetect content that would be helped by using the above progressive modes.

NTSC Film Mode

tvtime can detect a 2-3 pulldown sequence in the video stream and use this information to intelligently reconstruct frames. Enable this when watching an NTSC broadcast of a cartoon, film, or television program shot on film. The feature can be found in the in the input filters menu in tvtime.

The following is a table of the available deinterlacing modes and their names in the config file.

Short name Long name
TelevisionFull Television: Full Resolution
TelevisionHalf Television: Half Resolution
BlurVertical Blur: Vertical
BlurTemporal Blur: Temporal
AdaptiveSearch Motion Adaptive: Motion Search
AdaptiveAdvanced Motion Adaptive: Advanced Detection
AdaptiveSimple Motion Adaptive: Simple Detection
ProgressiveTFF Progressive: Top Field First
ProgressiveBFF Progressive: Bottom Field First

3. Using widescreen 16:9 mode

In 16:9 mode we treat the incoming signal as if it were 16:9 aspect ratio. If you're using a hardware DVD player, you should tell it that you have a 16:9 TV to get higher quality from your DVDs.

Setting to 16:9 on a Toshiba DVD player

The above screenshot shows the setup menu on the Toshiba SD-412V DVD player. Below is a screenshot of a scene from Koyaanisqatsi in 16:9 mode, giving the full vertical quality of the anamorphic DVD content.

An anamorphic DVD viewed in tvtime

4. Key bindings

Below is a table of the default key bindings in tvtime. Listed in the right hand column is the name of the setting in the tvtime.xml configuration file. See default.tvtime.xml file on the web or included with the tvtime distribution.

Key Description
  General use
Escape or q Quit
F1 or Tab Show menu
up/down Change channels
0-9 and Enter Change channels
Backspace Jump to previous channel
i Change input
m Mute
+/- Volume control
f Fullscreen
s Take a screenshot
d Display debug statistics
  Advanced
left/right Channel finetuning
< / > Overscan setting
e Toggle audio mode (stereo/mono/SAP)
a Change output aspect ratio
r Renumber current channel
v Toggle always-on-top with supporting window managers
p Toggle pulldown detection (NTSC only)
t Change deinterlacer
= Change attempted output framerate
F5/F6/F7 Picture settings
c Toggle closed caption decoding (NTSC only)
ins Change matte mode

5. Setting up your channel list in tvtime

tvtime supports a channel scanner, channel renumbering, channel names, and a list of active channels for browsing. All of these features are available within the OSD menu system itself. Here we present some of the details for users that wish to configure their stations directly.

European users of cable providers that do not use standard frequencies can use our channel scanner: tvtime-scanner. This outputs to the 'Custom' frequency table, selectable in the OSD menu.

stationlist.xml

The station listing is read in from the ~/.tvtime/stationlist.xml. Channel settings are saved specific to norm and frequency table. Entries in a list are in the following form:

       <station name="CNN" active="1" position="18"
                band="US Cable" channel="18"/>
       <station name="DSF" active="1" position="12"
                band="VHF E2-E12" channel="E12"/>

The possible bands and frequencies available in tvtime are:

Band name Stations provided
US Cable 1 - 125
US Two-Way T7, T8, T9, T10, T11, T12 T13, T14
US Broadcast 2 - 83
China Broadcast 1 - 68, A1 - A7, B1 - B31, C1 - C5
Japan Broadcast 1 - 62
Japan Cable 13 - 63
VHF E2-E12 E1 - E12
VHF S1-S41 S1 - S41
VHF Misc X, Y, Z, Z+1, Z+2
VHF France K01 - K10, KB - KQ, H01 - H19
VHF Russia R1 - R12, SR1 - SR19
VHF Australia AS1 - AS12, AS5A, AS9A
VHF Italy A - H, H1, H2
VHF Ireland I1 - I9
UHF U21 - U69
UHF Australia AU28 - AU69
Australia Optus 01 - 058

Custom frequencies can be included manually as follows:

       <station name="2" active="1" position="0"
                band="Custom" channel="55.69MHz"/>

Non-English characters in channel names

Since 0.9.8.2 it is possible to use non-English characters in channel names. To do this, you first need to specify a character set for the XML document. This is done by changing <?xml version="1.0"?> to for example <?xml version="1.0" encoding="ISO-8859-1"?>, depending on what encoding you want. If no encoding is specified, UTF-8 is assumed.

Note 1: If you want to display an & sign, you have to type &amp; since the file is XML.

Note 2: This non-English text support is not completely done yet. First of all, it probably only work properly on left-to-right languages which don't use any funky unicode features like combining characters. Also, the glyphs have to be in FreeSansBold.ttf. This rules out asian languages.

6. The tvtime.xml config file

tvtime's config file is written as an XML document. A default tvtime.xml file is installed to /etc/tvtime/tvtime.xml and documents each of the parameters. As well, there is a man page installed (man tvtime.xml) which also gives help for each of the parameters. An alternate config file may be specified on the command line using the --configfile option. Additional config files are loaded after reading defaults from /etc/tvtime/tvtime.xml and $HOME/.tvtime/tvtime.xml.

7. Controlling tvtime via tvtime-command

Modern PCs now have many custom input devices, such as remotes, multimedia keys, and voice recognition microphones. tvtime helps support alternate inputs through an application called tvtime-command. This application can send commands to control changing channels, adjusting volume, or navigating the menu without having to switch focus to tvtime. This allows for many extended features.

To send commands to tvtime, simply execute the tvtime-command program, along with any number of commands as its arguments. The following is a list of commands known to tvtime:

AUTO_ADJUST_PICT

Restores the picture settings (brightness, contrast, hue, colour) to their default values.

AUTO_ADJUST_WINDOW

Automatically resize the window to match the content inside it. This is for when you resize tvtime into, say, a long rectangle, and want it to jump back to being a perfect 4:3 box around the content.

The AUTO_ADJUST_WINDOW command was added in tvtime 0.9.8.3.

BRIGHTNESS_DOWN

Lowers the brightness setting on the input.

BRIGHTNESS_UP

Increases the brightness setting on the input.

CHANNEL_[0-9]

Simulates a keypad number press.

CHANNEL_ACTIVATE_ALL

Re-activates all channels in the list. Use this to re-initialize the channel list before running the scanner if you believe some channels are missing, or if new channels have become available.

CHANNEL_DEC / CHANNEL_DOWN

Move one channel down in the channel list.

The CHANNEL_DEC command was added in tvtime 0.9.8.1.

CHANNEL_INC / CHANNEL_UP

Move one channel up in the channel list.

The CHANNEL_INC command was added in tvtime 0.9.8.1.

CHANNEL_JUMP / CHANNEL_PREV

Changes to the last channel you were at. Useful for jumping back and forth between two programs on distant channels.

The CHANNEL_JUMP command was added in tvtime 0.9.11.

CHANNEL_RENUMBER

Renumbers the current channel. This will swap the current channel with the number you type in. Use this to configure your station list to suit preference or locality.

CHANNEL_SAVE_TUNING

Saves the current fine tuning settings as a custom channel in the station list.

CHANNEL_SCAN

Walks from the current position through the channel list, disabling any channels for which no signal is detected. This command is only available if signal checking is enabled.

CHANNEL_SKIP

Toggles the current channel as being active or disabled in the station list. You can use this to manually scan your channels and enable those with signal or disable duplicate stations.

COLOUR_DOWN / COLOR_DOWN

Decreases the input colour picture setting. This will make the image less colourful until it is black-and-white.

COLOUR_UP / COLOR_UP

Increases the input colour picture setting. This will give the image more colour.

CONTRAST_DOWN

Decreases the contrast setting of the input.

CONTRAST_UP

Increases the contrast setting of the input.

DISPLAY_INFO

This will re-display the OSD for the current channel, showing the channel information, current deinterlacer and framerate, the time, and input settings.

DISPLAY_MESSAGE

This will display a message along the bottom of the OSD. Useful for cron jobs or other scripts to send notifications to a user running tvtime.

The DISPLAY_MESSAGE command was added in tvtime 0.9.9.

DOWN

This command provides the dual functionality of channel down or menu arrow down, depending on whether the menu is currently active. This command is to be used together with the LEFT, RIGHT and UP commands.

The DOWN command was added in tvtime 0.9.11.

ENTER

Sends a virtual enter command. Use this when changing the channel:

    tvtime-command channel_1 channel_5 enter

will change to channel 15.

FINETUNE_DOWN

Decreases the fine tuning setting for the current channel.

FINETUNE_UP

Increases the fine tuning for the current channel.

HUE_DOWN

Decreases the hue setting of the input.

HUE_UP

Increases the hue setting of the input.

KEY_EVENT

Sends a fake keystroke event to tvtime. This is useful for doing complex operations via a remote control, as you can indirect events to tvtime's internal key binding system.

The KEY_EVENT command was added in tvtime 0.9.9.

LEFT

This command provides the dual functionality of mixer volume down or menu back command, depending on whether the menu is currently active. This command is to be used together with the RIGHT, UP and DOWN commands.

The LEFT command was added in tvtime 0.9.11.

MENU_DOWN

In menu mode, this command moves the cursor down one entry in the menu.

The MENU_DOWN command was added in tvtime 0.9.9.

MENU_ENTER

In menu mode, this command selects the current entry or moves forward one level in the menu.

The MENU_ENTER command was added in tvtime 0.9.9.

MENU_EXIT

In menu mode, this command shuts off the menu.

The MENU_EXIT command was added in tvtime 0.9.9.

MENU_LEFT

In menu mode, this command moves back one level in the menu.

The MENU_LEFT command was added in tvtime 0.9.9.

MENU_RIGHT

In menu mode, this command selects the current entry or moves forward one level in the menu.

The MENU_RIGHT command was added in tvtime 0.9.9.

MENU_UP

In menu mode, this command moves the cursor up one entry in the menu.

The MENU_UP command was added in tvtime 0.9.9.

MIXER_DOWN

Decreases the volume setting for the Line In device from /dev/mixer. An optional parameter specifies the percentage to decrease by.

MIXER_TOGGLE_MUTE

Toggles the mute status with the mixer, and not with the capture card like TOGGLE_MUTE does.

The MIXER_TOGGLE_MUTE command was added in tvtime 0.9.8.3.

MIXER_UP

Increases the volume setting for the Line In device from /dev/mixer. An optional parameter specifies the percentage to increase by.

NOOP

The command to do nothing. Useful for when you want to blank out one of the default key bindings in tvtime.

The NOOP command was added in tvtime 0.9.11.

OVERSCAN_DOWN

Decreases the overscan compensation amount. This will show more of the captured input.

OVERSCAN_UP

Increases the overscan compensation amount. This will show less of the captured input.

PICTURE

Selects which picture setting (brightness/contrast/colour/hue) to change using the PICTURE_UP and PICTURE_DOWN commands.

The PICTURE command was added in tvtime 0.9.9.

PICTURE_UP

Increases the current picture setting value (brightness/contrast/colour/hue).

The PICTURE_UP command was added in tvtime 0.9.9.

PICTURE_DOWN

Decreases the current picture setting value (brightness/contrast/colour/hue).

The PICTURE_DOWN command was added in tvtime 0.9.9.

RESTART

Asks tvtime to restart itself. This is used in the menu when we have changed a value that we can't yet change at runtime.

The RESTART command was added in tvtime 0.9.9.

RIGHT

This command provides the dual functionality of mixer volume up or menu enter command, depending on whether the menu is currently active. This command is to be used together with the LEFT, UP and DOWN commands.

The RIGHT command was added in tvtime 0.9.11.

RUN_COMMAND

Instructs tvtime to spawn a command. This can be used to start a program using a key in tvtime or lirc, such as to spawn mythepg or alevt. Using tvtime-command run_command "xterm" will have tvtime call system( "xterm &" ).

The RUN_COMMAND command was added in tvtime 0.9.10.

SAVE_PICTURE_GLOBAL

Saves the current picture settings as the global defaults.

The SAVE_PICTURE_GLOBAL command was added in tvtime 0.9.9.

SAVE_PICTURE_CHANNEL

Saves the current picture settings as the defaults for the current channel on the tuner.

The SAVE_PICTURE_CHANNEL command was added in tvtime 0.9.9.

SCREENSHOT

Asks tvtime to take a screenshot. Screenshots are saved to the directory listed as the screenshot directory in the tvtime.xml configuration file. The default is the running user's home directory.

SET_AUDIO_MODE

This command takes a parameter and sets the current audio mode. Valid options are "mono", "stereo", "sap", "lang1" or "lang2".

The SET_AUDIO_MODE command was added in tvtime 0.9.9.

SET_DEINTERLACER

This command takes a parameter and sets the current deinterlacer. Valid options are the short name of any of the deinterlacers available in tvtime.

The SET_DEINTERLACER command was added in tvtime 0.9.9.

SET_FRAMERATE

This command takes a parameter and sets the current framerate. Valid options are "full", "top" and "bottom".

The SET_FRAMERATE command was added in tvtime 0.9.9.

SET_FREQUENCY_TABLE

This command takes a parameter and sets the current frequency table.

The SET_FREQUENCY_TABLE command was added in tvtime 0.9.9.

SET_FULLSCREEN_POSITION

This command sets where widescreen output will be aligned when in fullscreen mode, either top for the top of the screen, center, or bottom.

The SET_FULLSCREEN_POSITION command was added in tvtime 0.9.11.

SET_INPUT

This command takes a parameter and sets the the capture card input (0-n). Among the Inputs are: the tuner, composite, or S-Video connectors on the capture card.

The SET_INPUT command was added in tvtime 0.9.14.

SET_INPUT_WIDTH

This command takes a parameter and sets the current input width in pixels. It will be used in tvtime after a restart.

The SET_INPUT_WIDTH command was added in tvtime 0.9.11.

SET_MATTE

This command sets the matte to apply to the output. This changes the size of the output window, and is useful for watching a 2.35:1 movie in a long, thin window, or for watching it at the top of the screen using the fullscreen position option. Valid options here are 16:9, 1.85:1, 2.35:1 or 4:3.

The SET_MATTE command was added in tvtime 0.9.10.

SET_NORM

This command takes a parameter and sets the current television standard. It will be used in tvtime after a restart.

The SET_NORM command was added in tvtime 0.9.9.

SET_STATION

This command takes a station name or number as a parameter and changes the channel to the station given.

The SET_STATION command was added in tvtime 0.9.13.

SET_XMLTV_LANGUAGE

Set the preferred language code for XMLTV data. The argument can be either the two-letter language code according to ISO 639 or a number to select one of the known languages.

The SET_XMLTV_LANGUAGE command was added in tvtime 0.9.13.

SET_SHARPNESS

This command takes a parameter and sets the current sharpness in pixels. It will be used in tvtime after a restart.

The SET_SHARPNESS command was added in tvtime 0.9.9 and replaced by SET_INPUT_WIDTH in tvtime 0.9.11.

SHOW_DEINTERLACER_INFO

Shows a help screen on the OSD describing the current deinterlacer setting.

The SHOW_DEINTERLACER_INFO command was added in tvtime 0.9.9.

SHOW_MENU

This command is used to bring up the tvtime setup menu.

The SHOW_MENU command was added in tvtime 0.9.9.

SHOW_STATS

Shows a debug screen showing statistics about the running instance of tvtime.

SLEEP

This command sets the sleep timer to tell tvtime to shut itself off after a certain amount of time. Sending this command will first activate the feature, and sending it again will increase the timer up until a maximum value at which point it is shut off.

The SLEEP command was added in tvtime 0.9.10.

TOGGLE_ALWAYSONTOP

If supported by your window manager, this command will ask to have the window be put into an "always on top" state, where no other window can be stacked above it.

The TOGGLE_ALWAYSONTOP command was added in tvtime 0.9.9.

TOGGLE_ASPECT

Toggles the display between 4:3 and 16:9 mode. Use 16:9 mode if you have configured an external DVD player or satellite receiver to output anamorphic 16:9 content.

TOGGLE_AUDIO_MODE

Toggles between the available audio modes on this channel. It can take some time before the driver discovers that modes are available.

TOGGLE_BARS

Asks tvtime to display colourbars. The colourbars are generated by tvtime and are not related to the capture card, but simply to help configure your video card and display device. Once your settings are correct with these colourbars, try colourbars from an input source like an external DVD player and make sure they match up.

TOGGLE_CC

Enables closed caption information to be displayed in the tvtime window. Closed captioning is only available if you have enabled VBI reading in your tvtime.xml configuration file.

TOGGLE_CHANNEL_PAL_DK

For PAL users, toggles the audio mode of the current channel between the PAL-BG and PAL-DK audio norms.

The TOGGLE_CHANNEL_PAL_DK command was added in tvtime 0.9.13.

TOGGLE_CHROMA_KILL

Enables or disables the chroma killer filter, which makes the input black and white. Useful when watching a black-and-white movie to avoid chrominance artifacts.

The TOGGLE_CHROMA_KILL command was added in tvtime 0.9.10.

TOGGLE_COLOR_INVERT / TOGGLE_COLOUR_INVERT

Turns on or off the colour invert filter. This is (apparently) useful for users of the Australian cable company Optus who want to avoid using the decryption boxes and tune using their capture card directly.

The TOGGLE_COLOUR_INVERT and TOGGLE_COLOR_INVERT commands were added in tvtime 0.9.9.

TOGGLE_DEINTERLACER

This toggles between the available deinterlacing methods.

TOGGLE_FULLSCREEN

This toggles between fullscreen and windowed mode.

TOGGLE_FRAMERATE

Toggles the framerate at which tvtime will output. Options are full frame rate (every field deinterlaced to a frame), half frame rate TFF (every top field deinterlaced to a frame) and half frame rate BFF (every bottom field deinterlaced to a frame).

TOGGLE_INPUT

Switches the capture card input used. Among the Inputs are: the tuner, composite, or S-Video connectors on the capture card.

TOGGLE_MATTE

Switches between the available mattes. This cuts off the top and bottom of the input picture to help fit the window to the image content.

The TOGGLE_MATTE command was added in tvtime 0.9.9.

TOGGLE_MIRROR

Turns on or off the mirror filter, which flips the input. This is useful for using tvtime with mirroring projectors, although I don't think it will actually work as intended yet since we don't mirror the OSD output. :) Comments appreciated.

The TOGGLE_MIRROR command was added in tvtime 0.9.9.

TOGGLE_MUTE

Toggles the mute state in the capture card (and not in your soundcard).

TOGGLE_NTSC_CABLE_MODE

Toggles the NTSC cable mode settings: Standard, IRC, and HRC are available.

TOGGLE_PAL_DK_AUDIO

For PAL users, toggles the default audio mode of all channels between the PAL-BG and PAL-DK audio norms.

The TOGGLE_PAL_DK_AUDIO command was added in tvtime 0.9.13.

TOGGLE_PAL_SECAM

Toggles between PAL and SECAM on the current channel. This feature is useful for regions which receive both PAL and SECAM channels, such that tvtime can be configured on a per-channel basis for the correct norm.

The TOGGLE_PAL_SECAM command was added in tvtime 0.9.9.

TOGGLE_PAUSE

Enters pause mode. Pause mode is a debugging feature used to test deinterlacer filters by allowing to see the output of a single set of frames with various deinterlacers.

TOGGLE_PULLDOWN_DETECTION

Enables or disables the 2-3 pulldown detection feature for NTSC input.

TOGGLE_SIGNAL_DETECTION

Toggles on and off tvtime's signal detection code. Signal detection enables features like channel scanning and increases responsiveness on channels with poor reception, but may make it impossible to watch stations where the reception is too bad for the card to detect it reliably.

The TOGGLE_SIGNAL_DETECTION command was added in tvtime 0.9.10.

TOGGLE_XDS

Toggles on and off tvtime's XDS decoding code. XDS is used to send information about the channel including the network name and call letters, and sometimes information about the current show. This information is then shown on the OSD and saved to the stationlist.xml file.

The TOGGLE_XDS command was added in tvtime 0.9.10.

TOGGLE_XMLTV_LANGUAGE

Toggles which language to show by default from the XMLTV file from the ones available in the file.

The TOGGLE_XMLTV_LANGUAGE command was added in tvtime 0.9.13.

UP

This command provides the dual functionality of channel up or menu arrow up, depending on whether the menu is currently active. This command is to be used together with the LEFT, RIGHT and DOWN commands.

The UP command was added in tvtime 0.9.11.

QUIT

Asks the running tvtime process to exit.