using_kmttg

USING KMTTG

NOTE: This documentation is updated to match latest kmttg release only.

NOTE: The first time you start kmttg you may be prompted to allow 3rd party tool download and installation which are used by kmttg as well as prompted for your Media Access Key (MAK). You can further configure kmttg as needed by selecting File->Configure… menu entry. See the [configuring_kmttg] wiki documentation for details on configuration options.

See also [keyboard_shortcuts] for summary of keyboard shortcuts for various kmttg tables.

Hopefully, the kmttg GUI is pretty intuitive to use. For more information on the Auto Transfers mode see the section further below. A little guidance is provided for basic usage of the GUI mode:

Updating kmttg

• Starting with version v1p0b you can now update kmttg installation to latest official version automatically using Help-Update kmttg... menu entry. kmttg will check your installed version against the latest available official version and prompt to update if they are different.
• You can also update helper tools now automatically using Help-Update tools... menu entry if running on Windows or Mac platforms. Starting with kmttg v1p0l, kmttg saves the last version installed and lists version last installed next time you use it again so you can determine if tool update is actually needed/wanted.

Remote

Starting with version v0p8i kmttg has a Remote tab which uses the reverse engineered rpc protocol to communicate with series 4 or later TiVos (won't work for older TiVos) to unlock several additional ways of communicating with the TiVo. You must first enable at least 1 TiVo series 4 or later in kmttg configuration TiVo tab: "Enable rpc style communications with this TiVo" in order for the Remote tab to be visible. See the [remote_control] wiki documentation for details on using the remote control GUI.

AutoSkip

Starting with version v2.1k kmttg has ability to import skip data for shows and automatically skip commercials while viewing on TiVo series 4 or later. See [AutoSkip] wiki documentation for details.

Disk Usage button

kmttg has a Disk Usage button for each TiVo tab. Clicking this button brings up a window showing a Pie Chart with a breakdown of how disk space is being used on this TiVo. Also shown at the bottom of the window is a table with an entry for each channel that you have recordings from and a summary of total space consumed per channel as well as the bit rate in Megabits per second (Mbps) and Gigabytes per hour (GB/hour). This is a measure of quality - the higher the bit rate the better the quality.

The first time you bring up this window you will need to set the proper value for Total Disk Space (GB) field at the top of the window. Enter the correct size for total disk space of this TiVo and then press Enter to update the window statistics and save the total disk space specification in kmttg configuration file.

Setting this option to 0 also will reset it such that it will display total used space thus far. This is in case user does not know in advance how much disk space is available for recordings.

Export... button

Can be used to export NPL entries to CSV spreadsheet format file.

NOTE: The table will be exported as it is displayed with current column order, sorting, and folders.

NOW PLAYING LIST

• There will be a separate tab in the main kmttg GUI for each TiVo configured and/or detected in your home. Each tab is named the same as you name your TiVo(s). Click on corresponding tab to select which TiVo you wish to interact with.
• In addition to TiVo tabs there is also a FILES tab and a Remote tab available which are explained later in the documentation.
• Select a TiVo tab and click on Refresh button to obtain listings for a TiVo.
• The 1st table column can have 1 or more symbols displayed. Consult [col1_symbol_meanings] Wiki for their meanings.
• Once the table is populated, left click on arrow for a folder entry to expand or contract all children in the tree. Alternatively you can double click anywhere in a folder row to toggle the tree view as well.
• You can automatically expand/contract all tree views using the t bindkey or right mouse button Tree state toggle menu entry.
• Left click on a table row that is not a folder to display more information about the show in the message window.
• Right click on a table row to bring up a popup menu with different actions available to operate on selected show.
• You can enable grouping of similar shows by enabling the Show Folders option.
• Table column widths are automatically adjusted to fit the contents unless you turn off Auto size NPL columns widths option under Configuration-Visual tab.
• If you have the RPC remote enabled for series 4 TiVos or later (see [remote_control] Wiki) you can use the keyboard delete button to delete shows from your TiVo or the play button to start playback of a show on your TiVo.
• Pressing keyboard j button on a show will dump all stored information for that show (used primarily for debugging purposes).

DOWNLOADING FROM TIVOS

kmttg uses a separate tab displaying the Now Playing List (A.K.A NPL or My Shows) of each Tivo on your network. The tabs will be the same names you gave to your TiVos. There is also always a FILES tab which allows you to find files on your computer to use as a starting point for kmttg (see documentation on this a little further down). Additionally any Tivos you have previously configured for kmttg will show up in their own tab so that you can use shows on your Tivos as starting points for kmttg. Use the Refresh button to refresh the Now Playing list for a Tivo.

To download shows in .TiVo format simply select 1 or more shows in the Now Playing List and click on START JOBS button. If you want to do further processing beyond just downloading then enable tasks such as "metadata", "decrypt" etc. according to what you need before clicking on START JOBS. All tasks are queued up and their status will display in the Job Monitor table. See START JOBS section below for more information.

The TS downloads option controls whether downloads you have selected download in mpeg2 Transport Stream (TS) container or mpeg2 Program Stream (PS) container. See further documentation on that option below.

NOTE: Shows that are still recording or are copy protected are marked as such and displayed differently by kmttg and cannot be downloaded.

Resuming Downloads

• Starting with version 0p8l there is a boolean menu item called Resume Downloads under File menu which when enabled signifies to kmttg to download shows from their pause point instead of from the beginning.
• This is useful for example for cases when you only get partial download because of a glitch in the recording. For such cases you can download the first part of the recording to the glitch point, then find the glitch point via playback on the TiVo and advance a little beyond it and then resume download from that point.
• This also can be useful if you only want to download a small segment of a recording. You can identify the starting point on the TiVo and set pause point there and then resume download via kmttg and cancel the download at ending point.
• NOTE: Resume downloads works best with Java Downloads configuration option enabled, so if you enable this option then kmttg will automatically enable Java Downloads.
• Consult [Resume_Downloads] Wiki for more information on how to use this capability.
• NOTE: Resume Downloads does NOT work for TS container downloads.

Show Folders

You can enable or disable folder display by toggling the Show Folders toggle button individually for each Tivo listing. Similar to Tivo listings shows will be categorized by same name, and "TiVo Suggestions". Left click on a table row that is not a folder to display more information about the show in the message window. Right click on a table row to bring up a popup menu with different actions available to operate on selected show.

Partially Viewed

This toggle is only displayed for series 4 or later TiVos - not available for series 3 or earlier TiVos.
You can toggle between full listing or listing of partially viewed programs only using this toggle button.
If you click on Refresh button with this option enabled it's a quick way to obtain NPL listings only for shows that have been partially watched. This can save a lot of time if you have many shows on your TiVo but are only looking to process partially viewed shows since only partially viewed shows are retrieved in this case.
If you want to view full show listings you may have to deselect this option and click on the Refresh button. After doing that you can toggle between full or partial listings again.

Show sorting

NOTE: You can sort shows in the list by clicking on the list headers:

* Clicking on 1st column header button you can sort shows by expiration type.
* Clicking on the **DATE** header button you can sort shows by earliest or latest date first.
* Clicking on the **CHANNEL** header button you can sort shows by lowest or highest channel number.
* Clicking on the **SIZE** header button you can sort shows by smallest or largest file size first.
* Clicking on the **SHOW** header button you can sort shows alphabetically or reverse alphabetically by show name.
* The **DUR** column is short for **DURATION** and you can also sort by this column.
* The **Mbps** column is a measure of bit rate in Megabits per second. The higher the bit rate displayed the higher the quality of the recording. You can also sort by this column.

Sorting

1st click on a table header sets ascending order for that column.
2nd click on a table header sets descending order for that column.
3rd click on a table header will restore table back to descending date order which is the default sort for the table when it is first displayed.

NOTE: You can change the column order to be whatever you prefer. Simply hold left button down on a column header and drag the column to new position. kmttg will save and restore column positions for each tab when you start next session.

TS Downloads

• If this option is enabled then kmttg will download selected shows in the table using mpeg2 Transport Stream (TS) container format. If disabled, then the download will be in mpeg2 Program Stream (PS) container.
• NOTE: Any TIVo recordings that are using H.264 encoding instead of mpeg2 MUST be downloaded with this option enabled, else you will only get audio in the download without video. Recordings using mpeg2 video can be downloaded in either TS or PS container modes.
• Advantages to TS downloads:
  • Allows H.264 recording downloads
  • Typically faster than PS downloads
  • Will not corrupt closed captions
• Disadvantages of TS downloads:
  • TS downloads are much more susceptible to glitches and corrupted or missing frames. This is due to the TiVo server, nothing that can be controlled by kmttg.
  • Decrypting TS downloads is much more susceptible to problems compared to PS downloads. "tivodecode" cannot be used to decrypt TS TiVo downloads. "tivolibre" program can handle TS TiVo file decryption, but there are known to be issues that can lead to non decrypted video frames or complete failure to decrypt. The cleanest method to decrypt TS TiVo downloads is using Windows DirectShow methods such as "DirectShow Dump" or "VideoRedo". Those programs only work on Windows platform and also require that you have installed at least a partial TiVo Desktop installation which has the DirectShow filter needed for decrypting TiVo files.

metadata

• If this option is enabled then kmttg will create a metadata file which will have same file name as the final video file name but with .txt extension at the end.
• This metadata file can be used by pyTivo when serving back shows on your PC to your Tivos to provide detailed information about the show. Without the metadata file if you serve .mpg (or non .TiVo files) back to your Tivos there will be no information about the shows when you view them from your Tivos.
  
  NOTE: According to pyTivo conventions this file should be the same name as your video file but with .txt extension added. Thus if you re-name your video file be sure to re-name this file as well.
• Starting with kmttg version 0p7d you now have more control over which video files to generate metadata files for. Under kmttg configuration Program Options tab use the metadata files setting to choose which file(s) to generate metadata files for.

decrypt

• Shows downloaded from your Tivos are encrypted mpeg2 program files saved with .TiVo file extension.
• With this option enabled kmttg will use tivodecode to decrypt .TiVo files to unencrypted mpeg2 program files with .mpg extension.
• Most often you will want this option enabled.

QS Fix

• This option is short for QuickStream Fix. Traditionally this meant VideoRedo QuickStream fix but ffmpeg is now used if VideoRedo is not available. VideoRedo will be used if configured in kmttg, else ffmpeg will be used if configured in kmttg.
• If you plan on any further processing of .mpg files such as cutting out commercials or re-encoding to different format it’s useful to run the file through QS fix first to fix any potential glitches in the .mpg file that may cause issues.
• Starting with version 0p7c there is now a configuration option called Enable VideoRedo QS Fix video dimension filter which is very useful if you ever have run into Video Dimensions Error when editing files in VideoRedo.
• ffmpeg fixes streams by remuxing audio and video streams with some specific options for setting timestamps.

Ad Detect

• This option is for automated commercial segment detection using either comskip or VideoRedo AdScan.
• comskip is a public domain program that can scan an mpeg2 file and detect commercials.
• If you are using VideoRedo you have option to use VideoRedo AdScan instead of comskip for commercial detection. Look at kmttg configuration under VideoRedo tab to turn on that option.
• When using comskip, if you using ffmpeg to cut commercials a .edl file is produced which is parsed by kmttg and used to cut out show segments using ffmpeg.
• When using comskip, if you have VideoRedo enabled then the comskip job will run with --videoredo option which will create a .VPrj file which contains the cut sections for VideoRedo to be used in the Ad Cut stage.
• If you have VideoRedo configured in kmttg you can enable option in kmttg to be able to manually review/edit detected commercials using VideoRedo GUI. To turn this on in kmttg configuration, VideoRedo section enable Use VideoRedo GUI to review detected commercials.
• Otherwise if you don't use VideoRedo, in kmttg configuration, Program Options section, there is an option called Use comskip GUI to review detected commercials. If you enable this option then when running kmttg GUI and following the Ad Detect task, kmttg will run a comskip_review task which brings up comskip visual editor. You can use that editor to review/modify detected commercial segments. Consult [comskip_commercial_editing] Wiki page for a summary of how to use the comskip visual editor.

NOTE: Accuracy varies greatly depending on the show. Comskip is most useful to use as an initial guess as to where cut points should be made. Ideally you should then use VideoRedo or comskip editor to adjust the cut points as needed.

Ad Cut

• This option is for automated commercial segment removal based on commercials detected in the Ad Detect stage.
• VideoRedo is used for this task if configured, else ffmpeg is used to automatically cut out commercial segments detected by comskip.
  NOTE: You are better off using an mpeg2 editor if you want precise cuts and in sync audio/video. The combination of Ad Detect and Ad Cut can work well for some shows but not well at all for others.

captions

• This option is only enabled on Windows systems and if you have configured full path to T2Sami t2extract.exe.
• This gives you the ability to extract closed captions from .TiVo or .mpg files to a .srt file.
• The file created will have same name as the video file but with .srt suffix.

encode

• Enable this option if you wish to re-encode .mpg files to another format.
• You should also select the appropriate Encoding Profile you want to use for the encode.
• You can define your own encoding profiles if you wish (see [encoding_profiles] Wiki).
  NOTE: If Ad Cut is enabled then the encoding will be done on _cut.mpg file instead of .mpg file.

atomic

• This task does not show up explicitly as a choice to run. However if you have AtomicParsley executable specified in kmttg config and you generate an mp4 or m4v file in the encode step AND you have a pyTivo metadata file to accompany the encoded file then this step will be run automatically by kmttg once encoding job completes. This takes information from the pyTivo metadata file and adds it to the video file so that programs such as Itunes can display extra information about encoded files.

• There is a Run AtomicParsley button available in FILES tab which can be used to explicitly run AtomicParsley on selected video files with mp4 or m4v suffix. There must be accompanying pyTivo metadata files to go along with the video files in order for this to work. i.e. If video file is myvideo.mp4 there should also be a myvideo.mp4.txt pyTivo metadata file to go along with it.

• There is a pyTivo stream button available in FILES tab if at least 1 TiVo in kmttg config has RPC (RPC style communications) enabled.

  • This allows you to stream video files to a series 4 or later TiVo using TiVoCast HME Video Player and pyTivo as a video server. You can choose a video file that resides under one of pyTivo video shares in the FILES table and then click on this button to stream it to a specified series 4 or later TiVo.
  • The advantage of streaming this way vs for example Streambaby is that there is no 1.1GB buffer limitation.
  • NOTE: This only works for unencrypted mpeg2 program stream and H.264 mp4 files that pyTivo can transfer without having to transcode. If you attempt to stream a non-compliant video that pyTivo transcodes this will not work. .TiVo files also won't work.

NOTE: When using File Browser to add video files to FILES list set Files of Type to video files in order to be able to see files ending in .mp4 or .m4v suffix.

custom

• You can use this option if you have configured a custom script to run in kmttg configuration. This is always the last task to be performed in the set of enabled tasks and gives you flexibility to do any custom actions you want.

START JOBS

Click on START JOBS green button to start processing all your selections.
* NOTE: Jobs that are not dependant on each other will run in parallel. Downloads are intentionally limited to 1 download per Tivo so as not to overload your Tivos. Additional downloads are queued up to be performed once the current download completes. Jobs that depend on previous jobs to complete are also queued up.
* kmttg will automatically skip steps based on the presence of files in the output directory. For example, if .TiVo file for a show exists kmttg will skip downloading it from the Tivo. If .mpg file for a show exists kmttg will skip the decode phase even if decode is enabled, etc.
* kmttg can smartly insert jobs into existing job set. So for example you start a download but forget to enable decrypt. Simply select the appropriate show and turn on only the decrypt option and click on the START JOBS button and kmttg will queue up the decrypt job and wait for download to complete before starting.
* NOTE: This button can be activated from keyboard by pressing s with 1 or more shows selected in the table.

CANCEL JOBS

You can cancel any queued up or running jobs if you wish. Select jobs you wish to cancel in the JOB MONITOR (Panel below the CANCEL JOBS button) and then click on the CANCEL JOBS button.
* NOTE: In general kmttg will not automatically delete partial output files that were being generated by a running job in case you wish to do something with the files, so if you don’t want them you should clean them up. There are options in the configuration setup you can enable to automatically delete files of intermediate tasks such as .TiVo files.
* NOTE: This button can be activated from keyboard by pressing c with 1 or more jobs selected in the jobs table.

NOTE: For jobs that are actively running you can double click on the entry in the JOB MONITOR to view more detailed output information for that job. A window will appear showing any stdout/stderr messages generated by the 3rd party tool that is running.

*NOTE: Starting in version 0p7c the Now Playing List table indicates which shows currently have running and queued jobs associated with them with a check mark icon and hour glass icon respectively. This makes it easy to see which shows you already launched for processing.

STARTING FROM FILES ON YOUR COMPUTER

• The FILES tab lets you use kmttg starting from video files already downloaded/installed on your computer instead of downloading from your Tivos. If you select this option then 2 buttons will be available in the GUI:
• Add... will bring up a file browser you can use to locate .TiVo/.mpg/.mpeg files on your computer you wish to process further with kmttg. Once you select files to add they will be added to the kmttg FILES list.
• NOTE: On Mac platforms you can browse to /Volumes folder to get to other disk volumes.
• Remove... button can be used to remove files you have selected to process in the kmttg FILES list.
  NOTE: This doesn’t remove the files from your computer, simply removes them from the kmttg FILES list.
• Note that you can also use Drag and Drop from your OS file browser to drop files directly into the FILES table instead of using Add... button.
• Rest of the flow is very similar to the section above describing DOWNLOADING FROM TIVOS.
• The Run AtomicParsley button can be used to run Atomic Parsley program to add metadata to mp4/m4v files based on pyTivo metadata files that must be accompanying the video file.
• The pyTivo stream button can be used to launch the TiVoCast HME program to stream a video file to a series 4 or later TiVo. Note that this depends on pyTivo as the video server, and a file selected to be streamed must be available in 1 of pyTivo video shares for this to work. Note that only TiVo compatible mpeg2 or mpeg4 videos can be streamed using this method. Any video file that is not already TiVo compatible will not work.

ENCODING PROFILES

See [encoding_profiles] Wiki for details on adding your own encoding definitions.

KMTTG AUTO TRANSFERS

Consult the [auto_transfers] wiki page for details on setting up and running auto transfers.

NOTE: Auto Transfers can be run in background mode as a separate kmttg process either as a service in Windows or a background job for Macintosh/Linux systems. Latest kmttg versions also provide options for running Auto Transfers in graphical mode.

File menu items

• Configure (Ctrl+o) - Bring up the kmttg configuration window. See the [configuring_kmttg] wiki for details.

• Refresh Encoding Profiles (Ctrl+e) - If you update any of the encoding file profiles .enc files under the encode folder you need either re-start kmttg or choose this menu entry to have kmttg re-parse the encoding profile files.

• Save messages to file (Ctrl+m) - A quick way to save all messages shown in message window to a file. The message window will print where the file is saved to: kmttg.log file saved to same folder as kmttg.jar file.

• Clear all messages (Ctrl+a) - Clear the bottom message panel of all messages.

• Resume Downloads - Signifies to kmttg to download shows from their pause point instead of from the beginning. This only works and is enabled for series 3 TiVos. See Resuming Downloads section of this Wiki above for more information on this feature.

• Jobs->Do not launch queued jobs - A toggle menu item that when enabled prevents queued jobs from launching.

• Jobs->Save queued jobs - Saves current set of queued jobs to a file so that they can be loaded back into kmttg in the future. Useful if you need to exit kmttg without losing queued set of jobs.

• Jobs->Load queued jobs - Load from a previously saved file a set of queued jobs to run in kmttg.

• Download Metadata (Ctrl+r) - For selected entries in a TiVo NPL table, download only the metadata file for each. NOTE: This always downloads metadata as .TiVo.txt files regardless of which tasks you have selected. NOTE: This provides a means to only download metadata for a show without having to schedule a download plus other tasks for it.

• Search Table... - Brings up a search dialog that allows you to search tables. This applies to currently displayed table with a SHOW column only. If a match is found the corresponding table row is selected.

• AutoSkip Table... - Displayed if you have config--AutoSkip functionality enabled and have at least 1 RPC enabled TiVo. Consult [AutoSkip] Wiki for details on this table.

• AutoSkip Service - Displayed if you have config--AutoSkip functionality enabled and have at least 1 RPC enabled TiVo. Consult [AutoSkip] Wiki for details on this feature.

• Exit - Exit kmttg. Also kills any background jobs started by kmttg in GUI mode that may still be running.

Help menu

• Help->About... menu entry brings up a window showing latest released version of kmttg available (with a link to that release) as well as links to the online kmttg documentation.
• Help-Update kmttg... will check your installed version against the latest available official version and prompt to update if they are different.
• Help->Update tools... updates helper tools if running on Windows or Mac platforms. Note that there is no tools version check so this can be used to install the latest available tools zip package regardless if you have installed it before or not.

Right Mouse Popup Menu

Most tables have a right mouse button popup menu that is available to use to execute a corresponding keyboard shortcut action.

• For Now Playing List table the menu entries corresponding to available key bindings are:

  • Get extended metadata - Get extended metadata for selected show (Same as pressing m and equivalent to right mouse button click in previous releases). NOTE: This is only displayed if extended metadata can't be obtained via RPC or middlemind.tivo.com.
  • Delete - Delete show from source TiVo for RPC or TiVoWebPlus enabled TiVos (Same as pressing Delete)
  • Play - Play show on source TiVo for RPC enabled TiVos (Same as pressing Space)
  • Show Information - For RPC enabled TiVos only display Show Information dialog (Same as pressing i)
  • Display data - Dump all available show information to message window (Same as pressing j)
  • Web query - Initiate show web query (Same as pressing q)

• For Remote ToDo, Won't Record, Season Premieres, Search, Guide, Deleted tables the following menu entries are available:

  • Show Information - For RPC enabled TiVos only display Show Information dialog (Same as pressing i)
  • Display data - Dump all available show information to message window (Same as pressing j)
  • Web query - Initiate show web query (Same as pressing q)

Slingbox tab

Consult the [slingbox_capture] wiki page for details on using kmttg to capture output from your Slingbox Pro or later model Slingbox.