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.

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:

Remote

Starting with version v0p8i kmttg has a Remote tab which uses the reverse engineered iPad protocol to communicate with Premiere TiVos (won't work for older TiVos) to unlock several additional ways of communicating with the Premiere. You must first enable at least 1 TiVo Premiere in kmttg configuration TiVo tab: "Enable iPad 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.

Disk Usage button

Starting with version 0.7c 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.

DOWNLOADING FROM TIVOS

Starting with version 0.6e kmttg uses a separate tab displaying the Now Playing List of each Tivo on your network. 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.

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.

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, "TiVo Suggestions" and "HD Channels". (Note that "HD Channels" category is intentionally named differently than on TiVo since it contains all recordings from HD channels regardless if they are actually HD or not). Simply single click on a folder to display the shows in the folder and then click on the Back button to return back to the top.

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.

NOTE: Starting with v0p6g release 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.

2. Select 1 or more shows in the SHOW list that you wish to download. You can select multiple entries at once. Ctrl+left click toggles individual selections without losing your selection list.

3. Enable actions you would like to perform on the selected list of shows. The actions (in order that they are generally performed) are:

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 as of version v0p8l it now includes alternative of using ProjectX. VideoRedo will be used if configured in kmttg, else ProjectX will be used if configured in kmttg. The Windows and Mac tools zip files now both include ProjectX.
• 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.
• ProjectX fixes streams by demuxing audio and video streams to separate files. kmttg then uses ffmpeg to mux them back together in mpeg2 program stream format.

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.
• With default configuration it will produce a .edl file which can be fed to mencoder to cut out detected commercial segments.
• If you have VRD 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.

NOTE: comskip can be configured to output several other files too such as a bookmark .mls file for Womble Mpeg Video Wizard or a cut file for VideoRedo. Consult comskip documentation for details.
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 Womble, VRD or similar 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.
• mencoder is used if you select the “comcut” option in kmttg 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 comskip and comcut can work well for some shows but not well at all for others. On occasion I find mencoder can produce out of sync audio/video files.
NOTE: If you have configured VRD then this stage will use VideoRedo for doing the video cuts instead of mencoder. Alternatively if you have ProjectX configured then it will be used instead of mencoder to do the cuts.

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 section below on Encoding Profiles).

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.

• Starting with v0p7l release there is now 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.

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.

push

• Enable this option if you wish to push video file(s) to a Tivo of your choice.
• This works in conjunction with pyTivo server to initiate pushes of video files to a TiVo. pyTivo server must be running and the file to be pushed should reside in a defined pyTivo share directory.
• In order for this task to be available you must define path to pyTivo.conf file in kmttg configuration (pyTivo tab). The TiVo you want to push to is also defined there. You can also use the Files to push configuration option to control which video files you want to push.
• Video files can reside anywhere below the top level directory of an existing pyTivo video share. If you try and push a video file outside a pyTivo video share it will fail, so make sure to define output directory of files you want to push via kmttg to be under a pyTivo video share somewhere.

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.

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

• NOTE: 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.
• NOTE: Starting with version v0p6g kmttg can now smartly insert jobs into existing job set. So for example you start a download but forget to enable decrypt. Previously if you then enabled decrypt and clicked on START JOBS again kmttg would try and decrypt the partially download .TiVo file. Now kmttg will queue up the decrypt job and wait for download to complete as is desired.

5. 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: 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 entry is a special TIVO cyclic entry which lets you use kmttg starting from .TiVo/.mpg/.mpeg files already downloaded/installed on your computer instead of downloading from your Tivos. If you select this option then 2 buttons will be added to 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.

• Rest of the flow is very similar to the section above describing DOWNLOADING FROM TIVOS.

ENCODING PROFILES

Kmttg installation comes with an encode folder that contains files with .enc suffixes. These files define the entries that are shown in the Encoding Profile cyclic in the main kmttg window. You can create more encoding profiles of your own by adding additional .enc files to this folder. Kmttg expects these files to be in a very specific syntax so it’s highly recommended if you create your own file to start with a copy of an existing one.

• Lines starting with “#” are comments and you can add as many comment lines as you wish since they are ignored.
• There are 3 keywords that should be present: <description>, <command>, <extension>. There should be only 1 line after each.
• If you require more than 1 command for your encoding then you can make a batch script and define that as the command to be run
• There are a few uppercase keywords that kmttg understands and will replace with full paths appropriately: INPUT, OUTPUT, FFMPEG, HANDBRAKE, MENCODER, PERL
• Starting with release v0p7l there are 2 new special keywords available that are intended for use with ffmpeg encoding profiles to work around inability to specify fixed height with variable width, or fixed width with variable height resolutions. kmttg uses ffmpeg to determine the display aspect ratio (DAR) of the input video file and then uses that ratio to compute what to use for corresponding WIDTH or HEIGHT dimension, rounded to nearest even number. The 2 special keywords are:
• #xHEIGHT - (Example: -s 640xHEIGHT) In this example if input DAR is 4:3 then HEIGHT would be computed as 480, if input DAR is 16:9 it would be computed as 360.
• WIDTHx# - (Example: -s WIDTHx360) In this example if input DAR is 4:3 then HEIGHT would be computed as 480, if input DAR is 16:9 it would be computed as 640.

NOTE: Look at encode/ff_iphone.enc as an example of a profile using this feature.

There are comments in the pre-defined .enc file which hopefully makes it pretty obvious how to properly define these files.

NOTE: You MUST use all lowercase file names with no spaces if creating your own .enc files.

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+s) - 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 - Clear the bottom message panel of all messages.

• Reset TiVo web server - This uses http://<ip>/TiVoConnect?Command=ResetServer which may help clear out conditions where TiVo is reporting <h2>Server Busy</h2> errors when attempting to download shows, which seems to be fairly common for Series 2 Tivos. It has also reportedly fixed issues with Series 3 Tivos not responding to downloads as well.

NOTE: You need to select the tab of the TiVo you wish to run this command on before selecting this menu item.

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

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

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