Skip to content

Advanced Topics

Jump to bottom
Hugh Mackworth edited this page Jun 9, 2022 · 22 revisions

Advanced Topics

Configuration options designed for advanced users

Artwork

For MPEG files (.MPG, .MP4, .MOV, or .M4V), cTiVo can embed a still picture inside the file to represent it in Finder, iTunes, iOS devices, or other players that understand this standard.

First (default case), you can choose the same image used by your TiVo to represent the show; this will be a series-wide image downloaded directly from your TiVo.

Secondly, you can choose fan-generated art from theTVDB.com website (although this is dependent on the series/episode/movie being in the database). With this option, you can then choose either episode-specific, season-specific, or series-wide artwork.

Thirdly, you can manually add artwork directly to an episode. With the "Art" column enabled in the Now Playing Table, just drag your preferred artwork on top of any existing (or blank) artwork. This will then be embedded in any downloads of that show. cTiVo will even update any pre-existing downloads with that image. You can similarly remove any artwork (manually added or automatic) by dragging the image to the Trash. If manual, this will delete the matching image file from disk and from any existing downloads.

Finally, you can store artwork in your download folder, but the filename has to be in a very specific syntax. Note that this is the mechanism that the drag/drop ability uses; it simply creates a file in the appropriate location.

The filename must start with the series title (e.g. "The Daily Show with Jon Stewart") with any slashes or colons replaced with dashes. Then you can create a series-generic file (no suffix), a season-specific file (suffix of Snn, or an episode-specific file (suffix of SnnEnn). Movies start with their title and optionally the movie year XXXX as a suffix (e.g. "Fight Club_1999")

These files can be in almost any format supported by the OS, and can be stored in the download directory itself or in a "thumbnails" subdirectory of the download directory. If you have enabled series-specific subdirectories within the download directory, they can also be in that directory, or in a "thumbnails" subdirectory of that subdirectory. Finally, if you want to specify an image directory, use the secret command defaults write ThumbnailsDirectory <path> in Terminal. If there is more than one image, it will choose episode-specific, then season-specific, then series-wide in that order.

To increase the chances of finding appropriate artwork, it will use the first one it finds in the following order:

  • Local episode-specific (SnnEnn)
  • Local season-specific (S00)
  • Local series-wide
  • Whichever online source (TiVo or TVDB) you specify
  • The other online source
  • Initial frame from video

For movies, the order is:

  • Movie title with matching year suffix
  • Movie title without year suffix
  • theMovieDB artwork (if enabled and available)
  • Initial frame from video

Especiallly if you use these facilities, consider giving back to theTVDB and theMovieDB by entering any missing information into their systems, including appropriate artwork!

Manual TiVos

Normally, cTiVo discovers TiVos on the local network automatically using a network technology called BonJour. Normally this will work fine, but if you need to enter a TiVo address manually or wish to access your TiVos remotely, you'll need to enter their information here. Simply use the Edit>Edit Manual TiVos menu item. This will show any TiVos you've previously seen or entered. Use the + button to add a new one, or the - button to delete one. If you'd like to temporarily delete one, just uncheck the "Enabled" button. You can get the TiVo's current local IP address from its Networks and Settings screen, although this may change over time, especially when your TiVo is restarted. For the local network, you should always use the ports provided (80/443/1413). You can also enable or disable any TiVo here, as well as set its Media Access Key.

Interestingly, you may also be able to use cTiVo remotely, although this can take considerable network ability and patience. Patience both in the sense of trial and error as well as in the upload bandwidth available on your connection to the Internet. You will need to set your router to pass external accesses on certain ports on your main IP address through to your TiVo. As you may be doing this for other devices as well, we also let you adjust the ports cTiVo uses to match whatever port mapping you're doing in your router. If you didn't understand this paragraph so far, then you probably shouldn't be doing this.

If you want to press ahead, your steps are:

  1. Configure your DHCP to reserve a fixed address for your TiVo.
  2. Set up your TiVo to use that address.
  3. Configure your router to map three external ports to your TiVo's ports 80, 443, and 1413.
  4. Provide those external ports to cTiVo.

So as an example, if your external router address is 12.34.45.56 and you want to use ports 3000, 3001, 3002 for your remote TiVo access and your local addresses are in the form of 192.168.1.xx and you want to assign 192.168.1.10 for your TiVo, then you would:

  1. Tell DHCP to start assigning addresses at 192.168.1.11
  2. Tell your TiVo to use fixed IP Address 192.168.1.10
  3. Tell your router to map external ports:
    • 3000 to 192.168.1.10:80,
    • 3001 to 192.168.1.10:443
    • 3002 to 192.168.1.10:1413
  4. Tell cTiVo to create a Manual TiVo named Remote using
    • IP address of 12.34.45.56
    • Port: 3000
    • PortSSL: 3001
    • PortRPC: 3002

As should be obvious, this is not for the faint-hearted. Configuring your router requires finding and using some rather arcane UIs, and if done incorrectly, can disable your Internet or TiVo access.

Note that whether this violates your terms of service with your cable company, TiVo Inc, your internet provider, any random film studio in Hollywood, or anybody else is also entirely up to you.

Edit Channels

Cable companies are transitioning from MPEG2 to the newer and more compressed MPEG4, aka H.264. The older Program Stream cannot transport a H.264 file, so cTiVo will automatically switch to Transport Stream when needed. While Transport Stream can be used for MPEG2 videos, this seems to be less reliable. Thus cTiVo tracks which channels require H.264 and will automatically switch when needed.

While this process is completely automatic, this screen allows you to see what's happening and control it if desired. These channels will get filled in as you download shows, based on whether or we see the characteristic failure of H.264 over Progressive Stream of no video, just audio in the downloaded file.

First, you can simply turn on Transport Stream for all downloads with the control at the top. Generally, "√" means Yes, "-" means maybe or unknown, and "□" means No.

  • SkipMode? specifies to use SkipMode on this channel. It's marked Yes when we've seen SkipMode on a channel, or it's one of TiVo's known channels.
  • Commercials? specifies that a given channel has no commercials, so don't bother doing comskip on it (e.g. PBS)
  • Use TS lets you control whether to use Transport Stream or not for a given channel. √ means "use TS". - means "cTiVo chooses" based on whether we have seen H.264 or not, and "□" means "use PS".
  • H.264? indicates whether we've seen a channel use H.264("√") or MPEG2 ("-") or none yet("□").

You can manually remove channels from this list by selecting them and hitting the Minus sign at the bottom, or add one by hitting the Plus sign.

If you'd like us to check all your channels, then click on Test All Channels. This will add a show from every channel your TiVo has recorded (including Suggestions) with a special TestPS Format. This Format only downloads a short segment from each show to quickly test every channel. You can then remove all such Tests with the final Remove All Tests button. This is not required as each channel will simply retry the first time we see a PS failure, but it can be interesting to see what channels have converted.

Edit Formats

If you'd like to configure a different video encoder, or provide different parameters to the built-in ones than we have configured, then you can use the Edit>Edit Formats menu item. This gives you a screen where you can configure a new encoder format, or use an existing format as a template.

")

  • Start by selecting the closest Format from the Formats pulldown.

  • If it's a built-in Format, Duplicate it to create a new one that you can modify with your new parameters. You cannot edit a built-in format without duplicating it. You could create one from scratch with New, but it's probably easier to modify an existing one. Obviously, if you no longer want a user-defined format, you can Delete it here as well.

  • There is a special case for Handbrake as they have many built-in presets, and you can even define your own as well in their GUI. Just select any built-in Handbrake Format and pull down the preset menu on the right. This will create a new User Format with that preset, which you can then modify as you see fit.

  • All formats can either be hidden or visible in the main user interface. So if you don't have any use for any of the built-in formats, just turn off Show in User Interface. Similarly, we hide many that are not commonly used, just check that box to use them.

  • Below the line are all the parameters available for editing. Again, built-in formats cannot be edited without Duplicating, so their parameters will be greyed out.

  • Name as displayed in the menu. This must be unique versus all other built-in or user formats.

  • File Extension for Encoded File. cTiVo will use this to generate the filenames. Some encoders ignore an incorrect extension, and put the correct one in, which will cause problems, so be sure this is correct.

  • Description. This is just a short human-readable reminder of what the other options mean.

  • Input Filename/Output Filename/Edit List Switch: these are passed in the command line to the encoder (see Arguments

  • Encoder to Use: See Encoder To Use

  • Regex for Encoder Log: If the encoder cannot support simultaneous encoding (e.g. HandBrakeCLI), the encoder should provide in its standard output the percentage complete as a number from 0-100.  You will need to provide a regex expression for extracting this number from the last few lines of the standard output.  For example, HandBrakeCLI writes its progress as 87 %, so the regex is ([\% This will only be used when doing sequential downloading, decrypting, and encoding.  When doing simultaneous encoding, the data flow through the pipes is used to measure progress.

  • Video/Audio/Other Options for Encoder: These are passed on the command line to the encoder; see Arguments.

  • Comskip Options: ComSkip is an experimental feature for cTiVo; See the comskip project. Included in this implementation is a configuration file (comskip.ini), which can be found on the [cTiVo source code page/cTiVo/comskip.ini). In addition to other command line parameters, you can replace the built-in comskip.ini with your own comskip.ini file by entering "--ini=<full path>/comskip.ini" providing the full path to your own file.

  • ccExtractor Options: ccExtractor exports subtitles from the video stream into a .srt text file. See the ccExtractor project

  • Can run download and encode at same time should be set only if the encoder can run as a final stage of a pipeline (stdin being the source pipe).

  • Can be added to iTunes means that the file format generated is compatible with iTunes, and will simply enable or disable that option for the user.

  • Can Skip Commercials means whether to enable that option for the user. If enabled, the encoder must handle the edl as generated by comSkip.

Encoder to Use

Enter either the name or the full path to the encoder to be used. The paths searched for the encoder are (in order)

    	<cTiVo Bundle>
    	/usr/local/bin
    	/opt/local/bin
    	/usr/local/<encoder name>/bin
    	/opt/local/<encoder name>/bin
    	/usr/bin
    	<Full path>

If the encoder accepts - (dash) for standard input, you should check 'Can run download and encode at the same time' to allow simultaneous encoding. The encoder must be marked as executable. mencoder & HandBrakeCLI are included in the cTiVo bundle.

Your encoder can be a script file (with standard first line of #! to specify script type, such as #/usr/bin/sh for shell script or #!/usr/bin/osascript for Applescript), provided it accepts the above arguments and is marked as executable. Be sure to test script-based encoders with shows having special characters like single or double quotes or Unicode characters in their names.

Arguments

The command line passed from the options are:

    	<Video options>
    	<Audio options>
    	<Other options>
    	<Edit List Switch>   //These two only if running comSkip to skip commercials.
    	<.edl FileName>
    	<outputFileSwitch>
    	<<outputFileName>>
    	<inputFileSwitch>
    	<inputFileName>

OR, if no outputFileFlag:

   	    <Video options>
    	<Audio options>
    	<Other options>
    	<EDL Switch>		//These two only if running comSkip to skip commercials.
    	<.edl FileName>
    	<inputFileSwitch>
    	<<inputFileName>>
    	<<outputFileName>>

If you are debugging a format, you can use the advance preferences to increase the debugging level. See Log Files below for more information. You can also set the "Don't Delete tmp files" option, which will save the subsidiary program log files (from your encoder, comskip, etc) for your perusal. Be sure to set it back when finished debugging as it will generate massive temp files.

Advanced Settings

There are a few preferences that are intended for debugging purposes or for very advanced users only. These are in the Advanced Preferences screen.

  • Export Metadata to pyTivo will save the metadata in a .TXT as defined by the pyTiVo program (which lets your Mac act as a TiVo server over the network). This allows the information to go on a round-trip to your TiVo. Note that this option is not required if you are using MP4 files and a recent version of pyTiVo as we now store the metadata in a compatible format within the video file.

Delete from TiVo after download

If you view your TiVo as a collection device, and then watch your shows on another system (such as AppleTV through iTunes, or Plex), then this option will tell cTiVo to automatically delete all shows after they have been successfully downloaded. (Agreed that there is nothing particularly advanced about this option, but dangerous if that's not what you want to happen.)

Don't Delete tmp Files

During its processing, cTiVo creates several intermediate files, which are deleted upon completion. The video files are typically in the download directory, and the others (sub-program log files, etc) are in the /tmp/cTiVo/ directory. For debugging purposes, this option lets you turn off the automatic deletion. Setting this option can burn up your hard drive space very quickly, so be sure to disable after debugging!

Don't use memory buffer for downloads

For performance reasons, cTiVo will normally download the TiVo file into memory rather than writing it to a temporary file. Sometimes for debugging purposes, it's convenient to have it write these files directly to disk, and this option enables that.

Opt-out of Crashlytics reporting

If cTiVo crashes, it will report to us where in the program that occurred on the next startup, unless this option is checked. In addition, cTiVo reports success/failure rates for different Formats. This information is reported anoanonymously and helps us fix any problems, but you can opt-opt here if you choose.

Download Retries

If cTiVo encounters a failure (network not available, encoder problem, etc), it will retry automatically. This option lets you change the number of times it retries before giving up entirely; default is 3. Note that zero retries means try the main time then give up, so 1 attempt.

Concurrent Encoders

This controls how many simultaneous download processes we will launch. Note that regardless of this setting, each TiVo will only transfer one show over the network at a time. However, as encoding generally takes much longer than transferring, the number of encoders tends to be the limiting factor. Default is 2.

TiVo Refresh Rate

How often (in minutes) should cTiVo check the Now Playing list of your TiVos. Default is 0, which means 4 hours for TiVos capable of RPC, and 15 minutes for older TiVos (Premiere, HD or older).

Decode With:

The .tivo files we download are encrypted with your Media Access Key (MAK), which is why cTiVo needs that key to convert your shows. The old program "tivodecode" doesn't handle Transport Stream at all. Two new programs, tivodecode-ng and TivoLibre, do handle that as well as the H.264 compression format. So there is now a pull-down in Advance Preferences to choose which decryption to use. We recommend tivodecode-ng; the alternative, TiVoLibre may handle more cases, but requires Java runtime to be installed on your Mac, which Apple no longer recommends. If you don't have Java, TivoLibre will be disabled in the menu.

Temporary Files Directory

While the video files are stored in the download directory, during processing many other files are stored in a working directory. By default this is in the user's tem, and is emptied as each transaction is finished and when cTiVo starts up. As these files can be large, you can change this directory here.

Filename Template

This lets you control exactly how to name video files after they are downloaded. See Filename Templates

View TVDB Statistics

Displays the results of theTVDB lookups since cTiVo has started, or since an Empty Cache command. See theTVDB for more on interpreting this information.

Empty Caches

Empty Caches erases the caches stored in the program and reloads the information contained. The two caches are theTVDB information, the RPC information, and the detailed XML loaded from the TiVo for each show. Be warned that if you have hundreds of shows on your TiVos, this will generate a lot of network traffic. If you think something is wrong with the information being displayed, this might be useful, but more important reason for this command is to reset theTVDB statistics to go directly to the source rather than using the cache. See theTVDB below for more information.

Master Debug Level and Module Debug Levels

This will increase the level of detail written to the Console log from tracking None to Verbose for all modules. As "verbose" is indeed very verbose, you can also set the debug level separately for each of the major modules in the program at the bottom of this screen. This would mainly be of use while reading the source code or under the direction of someone helping you debug a problem. See Logging for more information.

Note if you have a problem during startup, you can hold down Control and Option during launch to change all modules to Verbose. As operating in Verbose mode all the time is not recommended, cTiVo will automatically switch from Verbose to Major unless you hold down Control-Option during startup.

TheTVDB

For some reason, TiVo stopped filling in the season/episode information on many shows, but does provide it through the RPC mechanism. Sometimes this information is inaccurate, and if you prefer theTVDB's season/episode information, you can check the box in Preferences.and we will look up an episode to fill in.

Fair warning: the following paragraphs on how this all works is way more information that you may want!

There are several steps involved here, and as theTVDB is fan-maintained, the process is not always successful. TiVo used to license show information from the Chicago Tribune Media Services company Zap2It. This information is organized by Episode IDs, which look like EPnnnnnnnnmmmm, where the N's are 8 digits representing a series ID, and the 4 M's specify the episode within that series. However with the transition to Rovi data, this EpisodeID has changed and is no longer compatible with theTVDB.

First we have to match the series, which is done by title name, which can lead to multiple matches (and we have to handle season subtitles, such as 24: The Lost Weekend). Then to find an episode, we match on "Original Air Date" as listed in both databases. This works well overall, but there is one major problem. If a show is first shown in one country and then shown again in another (e.g. Doctor Who, or most shows on BBC America), theTVDB considers them the same series and uses an Original Air Date from the first country. On the other hand, TiVo considers them separate series and uses the second country's Original Air Date. With the new TVDB database, we then look for the episode by SxxExx number and then by name, so we get much better coverage.

Finally, if we do find the episode, then we can then use the fan artwork, if any exists for that show. And if TiVo does not happen to have that season/episode info (especially on older TiVos), we can use theTVDB's instead. Note that there are frequent cases of season/episode mismatch, where theTVDB has a different information than TiVo provides, we've chosen to follow TiVo's lead, but you can change then in Adv Preferences.

There are two buttons relevant to this process in the Advance Preferences window. The first is View TVDB stats, which shows you the result of this process summarized since the program began. Note that for performance reasons, we cache the TVDB results, so if you want a true picture of the results for the current list of shows, you will need to use the other button Empty Caches. After a few seconds (or even a minute or two), View TVDB stats will show you how many series were found (and by which method), which episodes were then found, and how many episodes matched, and which ones didn't match.

    {
        "Episode Found" = 20;
        "Episode Found in Cache" = 16;
        "Episode Not FoundCount" = 17;
        "Episode Not FoundList" =     {
            "Access Hollywood" = "EP00188707 aired 2013-07-03 http://thetvdb.com/?tab=series&id=70829 ";
            "Antiques Roadshow: Vintage Milwaukee" = "EP00203652 aired 2013-07-01 http://thetvdb.com/?tab=series&id=83774 ";
            "Entertainment Tonight" = "EP00001457 aired 2013-07-04 http://thetvdb.com/?tab=series&id=70640 ";
            "Masterpiece Classic: Mr. Selfridge: Part 1" = "EP01088332 aired 2013-03-31 http://thetvdb.com/?tab=series&id=193131 ";
            "Selling New York: The Push" = "EP01231570 aired 2010-05-27 http://thetvdb.com/?tab=series&id=215131 ";
            "The Doctors: Must-Know Gadgets, Gizmos and Health Trends" = "EP01074571 aired 2012-11-08 http://thetvdb.com/?tab=series&id=242951 ";
            "The Wendy Williams Show: Mistresses" = "EP01061654 aired 2013-06-05 http://thetvdb.com/?tab=series&id=262904 ";
            "Throwdown With Bobby Flay: Fried Chicken" = "EP00841501 aired 2007-01-24 http://thetvdb.com/?tab=series&id=112581 ";
            "Wipeout: Boss & Employee: Third Shift" = "EP01046187 aired 2013-05-30 http://thetvdb.com/?tab=series&id=77253 ";
        };
        "Season/Episode Info Added" = 15;
        "Season/Episode Info Match" = 16;
        "Season/Episode Info MismatchCount" = 5;
        "Season/Episode Info MismatchList" =     {
            "MythBusters: Painting With Explosives; Bifurcated Boat" = "12/9 v our 92/6; EP00557678 aired 2013-06-26; http://thetvdb.com/?tab=series&id=73388 ";
            "Phineas and Ferb: Knot My Problem; Just Desserts" = "4/16 v our 44/3; EP00948847 aired 2013-07-05; http://thetvdb.com/?tab=series&id=81848 ";
            "Raising Hope: The Walk for Runs" = "3/8 v our 3/6; EP01279218 aired 2012-11-27; http://thetvdb.com/?tab=series&id=164021 ";
            "Raising Hope: What Up, Bro?" = "3/6 v our 3/4; EP01279218 aired 2012-11-13; http://thetvdb.com/?tab=series&id=164021 ";
            "The Ellen DeGeneres Show" = "10/169 v our 10/162; EP00599270 aired 2013-05-30; http://thetvdb.com/?tab=series&id=72194 ";
        };
        "Series Found EP" = 25;
        "Series Found SH" = 1;
        "Series Found by NameCount" = 1;
        "Series Found by NameList" =     {
            "Sandwich King: Comfort Food Classics" = "tvdb has (null) for our EP01432865; http://thetvdb.com/?tab=series&id=251478 ";
        };
        "Series Not FoundCount" = 4;
        "Series Not FoundList" =     {
            "Bang for Your Buck" = EP01131026;
            Challenge = EP00876404;
            "Extreme Waterparks" = EP01071497;
            "House Hunters: Beachfront Homes" = EP01413091;
        };
    }

For those series where episodes weren't found or mismatched, a URL is provided to go to theTVDB and update their information if appropriate. Note that huge controversies have erupted about how to number seasons and episodes, so just because TiVo is providing one set of information doesn't necessarily mean that theTVDB is incorrect or will take kindly to being changed. See their forums for more context. On the other hand, series that are missing episodes or lacking information at all are probably good candidates to fix in the central database for the benefit of all.

Advanced Subscriptions

For the basics of subscriptions, see Subscriptions. Under the covers, manual subscriptions are actually implemented using standard Regular expressions, which you can enter by hand. Regular expressions are quite complicated, and a description of how the work is way beyond the scope of this document. The offical syntax is at ICU syntax.

As an example, if you want all shows beginning with "House" and you just entered "House", you would get "Warehouse 13" shows as well. Instead, add the ^ (meaning "beginning of string") as ^House, which would match "House" or "House Hunters International", but not "Warehouse 13".

If you want the subscription table to look a little better, you can add <Display Name> after the regex and it will display that string rather than the regex used. So, if you only want "House", you might use ^House$ which is what a manual subscription does.

As another example, the shortcut ALL to download all recorded shows is implemented with .*<<<ALL SHOWS>>>, so the dot-star will match all recordings, and it will display as <<ALL SHOWS>> in the list.

Filename Templates

By default, cTiVo will save the downloaded files as SeriesName- EpisodeTitle.ext; for example, The Big Bang Theory- The Hofstadter Insufficiency.mp4. However, for some environments, a different filename format might be desired. For example, Plex likes to see filenames like The Big Bang Theory - S07E01 - The Hofstadter Insufficiency.mp4.

To make filenames configurable to whatever format you choose, you can provide cTiVo a filename template with embedded keywords in [brackets]. cTiVo will then use that template, replacing each keyword with the appropriate value for the show being downloaded. (FYI, This system is based on KMTTG’s filenaming format to make it easy to move back and forth from that system.)

You set this Filename Template in cTiVo’s Advanced Preferences. Just type it into the template; although for easy entry, you can use the pulldown menu on the right to fill in individual keywords. In addition, at the bottom of the list, we have also provided a few default formats; for example, two Plex formats: one for a shared directory, one for a structured directory with individual folders for each show and each season of a show. (Note that you probably want to turn off the "Create Sub-folders for Series" option if you use these directory options.)

The keywords below refer to the same example, specifically using the seventh season, first episode of Big Bang Theory called The Hofstadter Insufficiency first aired on 9/26/13, recorded on a TiVo named Main on Thursday, 10/17/13 at 8:00pm on channel 706 KOINDT.

The keywords available, and the results for this case are:

[title] = The Big Bang Theory – The Hofstadter Insufficiency
[mainTitle] = The Big Bang Theory
[episodeTitle] = The Hofstadter Insufficiency
[channelNum] = 706
[channel] = KOINDT
[min] = 00
[hour] = 20
[wday] = Thu
[mday] = 17
[month] = Oct
[monthNum] = 10
[year] = 2013
[originalAirDate] = 2013-09-26
[season] = 07
[episode] = 01
[Guests] = Stephen Hawking
[EpisodeNumber] = 701
[SeriesEpNumber] = S07E01
[ExtraEpisode] =                    //If cTiVo guesses this is a two-episode show, it will include the second one here "E01"
[startTime] = 2013-10-17T04-00-00Z  //“zulu” time
[TivoName] = Main	     
[Format] = Default                  //which Format did cTiVo use for this conversion
[movieYear] = 	                    //non-Movies don’t have a movieYear  
[TVDBSeriesID] = 80379              //from website tvdb.com 
[/] = subdirectory separator        //see below

Example templates: cTiVo default: [mainTitle]- [episodeTitle] //or just a blank field ==>The Big Bang Theory- The Hofstadter Insufficiency.mp4

Plex: [mainTitle] - [SeriesEpNumber] - [episodeTitle] ==>The Big Bang Theory - S07E01 - The Hofstadter Insufficiency.mp4

Other: [title] (Recorded [month] [mday],[year],[channel]) ==>The Big Bang Theory- The Hofstadter Insufficiency (Recorded Oct 10, 2013, KOINDT).mp4

If that’s not complicated enough for you, just wait; there’s more!

You can include a subdirectory separator keyword [/] to separate your downloaded files into separate subdirectories. For example, [mainTitle][/][seriesEpNumber] would create a subdirectory of your cTiVo folder for each separate series, wherein each show would be just named like S02E01.mp4 (maybe not a good idea). This feature allows you to emulate (or modify) cTiVo’s Create SubFolders for Series option. As an aside, the subFolders option occurs “first”, so you could use that option to divide the main folder into series folders, and then use the subdirectory keyword to divide those folders into seasons, if you wished.

Example: emulate cTiVo subdir Feature: [mainTitle][/][mainTitle]- [episodeTitle] ==>The Big Bang Theory/The Big Bang Theory- The Hofstadter Insufficiency.mp4

And more!

Depending on various issues, certain fields may not be available. The most obvious example is that movies don’t have season/episode information, but do have 'movieYear' information. So you can create a compound keyword, which contains one or more keywords separated by spaces as well as literal text in quotes. If ANY of the keywords included in the compound keyword are empty, then the ENTIRE compound keyword becomes empty. So, the compound keyword [" (" SeriesEpNumber ") “] would become (S07E01) for our episode above, but be omitted for a movie. Alternatively, the compound keyword [“ (“ movieYear “ )”] would represent (2013) for a movie released that year, but be omitted entirely for our episode of Big Bang, as movieYearwould be blank.

Example: naming a show with either season information OR movie information, as available: [mainTitle][" (" movieYear “)"] [" (" SeriesEpNumber ") "][" - " episodeTitle] ==>The Big Bang Theory - S07E01 - The Hofstadter Insufficiency.mp4 ==>Machete (2010)

And you can put these together: [mainTitle / "Season " season / mainTitle " - " seriesEpNumber " - " episodeTitle]["Movies" / mainTitle " (" movieYear ")"] ==>The Big Bang Theory/Season 07/The Big Bang Theory - S07E01 - The Hofstadter Insufficiency.mp4 ==>Movies/Machete (2010)

A couple of final notes:

  • Capitalization is irrelevant in keywords.
  • Quotes are not allowed inside quotes.
  • Brackets cannot be used as text.
  • Colons are converted to dashes.
  • You cannot control the extension of the filename here; that is determined by the format you choose.

Pushover Integration

Pushover (pushover.net) is a real-time notification system](https://pushover.net/). Due to user requests, cTiVo will now let you know when your shows have completed. To use it, you'll have to sign up with their system, which will give you a userId. Download the Pushover AppleScript, and save it in ~/Library/Application Scripts/com.cTiVo.cTiVo/DownloadDone.scpt . After the first successful download, the script will ask for your Pushover userId. (While this process is admittedly a little tedious, it only has to be done once, and Pushover reports back how many people are using the service. if a lot do, then I'll include turning on the script in the UI.)

Post-processing Hook

If you wish to do any processing on the file after download, you could use the same hook the Pushover integration uses to do any post-processing on downloaded shows that you wish. Create an AppleScript file and store it at ~/Library/Application Scripts/com.cTiVo.cTiVo/DownloadDone.scpt. Note that your AppleScript can do anything it likes, such as asking the user for information, or calling a shell script as demonstrated in the Pushover script, which asks for userId, manipulates the image, and then creates a shell script to call curl.

Documentation essentially consists of looking at (most likely just modifying) the Pushover script. if the DownloadDone.scpt file exists, cTiVo calls a routine downloadDone with the following parameters:

  • success: 1 if file is successful, 0, if a failed try, or -1 if final failure
  • showTitle: full name of show seriesTitle - episodeTitle. e.g. Doctor Who - Survival
  • filePath: location of output video on disk e.g. ~/Movies/TiVoShows/Doctor Who - Survival (S26E14).mp4
  • episode: season/episode information e.g. S26E14
  • startTime: ISO-format time string, e.g. 2018-04-02T07:59:58Z
  • tiVoName: TiVo that recorded this show, e.g. Living Room
  • imagePath: filename of image for this episode, e.g. ~/Library/Caches/com.cTiVo.cTiVo/TiVo Images/Doctor Who.jpg

The script is called after everything else is completed and show marked as Done/Failed, including transfer to Apple TV, etc. The text returned from the script call is printed to cTiVo's log. The script can take as long as it likes, but MUST return to free up the processing thread used by cTiVo.

Note that the Pushover script also has a sample "DownloadDoneEcho" routine, which just returns the values provided.

Log Files

cTiVo stores its main log files at ~/Library/Logs/cTiVo. The last four files are kept with up to 10M each. They are named with random numbers, so use the creation date to figure out the order. These files can be opened in any text editor, or the Console application, which provides a nice filter option.

As there's an enormous amount of data flowing through cTiVo, we let you control the amount of logs generated by the different parts of the program. There are five levels:

  • None: No output generated
  • Normal: General tracking of events
  • Major: Key points in the work flow
  • Detail: Detailed work flow
  • Verbose: Logs of all major data elements

Go to Advanced Preferences (Option-Cmd-Comma) to set these levels. The main objects in the program, at least the ones that generate log information, are:

  • AppDelegate: The main program
  • TivoManager: Holder of the major data items and cross-!TiVo activity
  • TiVo: Communicating with an individual TiVo
  • TiVoRPC: Real-time communications with the TiVo
  • TiVoShow: A show as stored on a TiVo
  • Download: The process to copy a show to the Mac
  • Format: Which encoder and parameters to use for a download
  • EDL: Edit Decision List (generated by comskip to indicated where commercials begin/end)
  • SRT: Sub Rip Text (subtitle format as generated by ccextractor )
  • iTunes: Communication object with iTunes
  • Task: An individual activity, such as commercialing, or decoding to be monitored
  • TaskChain: A set of Tasks to be executed in parallel
  • TVDB: Communications with theTVDB website
  • Subscription: A request to store all episodes of a series

In addition, there are the User Interface Components, which log user requests:

  • MainWindowController
  • ProgramTableView
  • DownloadTableView
  • SubscriptionTableView

While diagnosing an issue, you probably want to set all components to at least Major, with relevant ones to Detail and the one you're most interested in to Verbose.

For example, if you're interested in debugging a new encoding format, most of the debug activity you'll be interested in will be in Download, so set that one and Format to Verbose. In the event of a failure, this will include the recent entries in the sub-program's (e.g. encoder, comskip etc) log files to help you diagnose the issue.

Beyond the Normal level, the logs are primarily intended as a guide to which part of the code is being executed, so it's best to read them in conjunction with the source code. One string to filter on is "DL Status", which shows the transitions each show makes from one phase to the next. To get maximum information about a download, also set Task and TaskChain to Detail or Verbose, although this generates a lot of data.

Hidden Options

There are a few options that are not presented in the user interface. This choice is based on not many people choosing this option OR not much testing being done. These options are subject to being removed at any time, particularly if any support problems emerge. To set these, use the OS X defaults command in Terminal, e.g. defaults write com.cTiVo.ctivo MaxNumberEncoders 3 or defaults write com.ctivo.ctivo KeepSRTs -bool YES, then use defaults read com.cTiVo.ctivo to lock them in.

  • MaxProgressDelay* - How long to wait between status updates before declaring an encoder has crashed in seconds; default is 120
  • ThumbnailsDirectory* - Where to look for artwork thumbnails; default is either <download directory> or <download directory>/thumbnails; delete entirely to restore to default
  • KeepSRTs* If set to YES, will keep subtitle files (.SRT) even when included inside MP4 files.
  • TrustTVDBEpisodes* If set to YES, will override TiVo's episode numbers when they conflict with TVDB.

TiVo Certificates

To enable RPC features, cTiVo needs a non-expired certificate from TiVo. Versions 3.4.4, 3.4.5, and 3.5.3 (for MacOS 10.9/10, 10.11, and 10.12 onward respectively) contain a certificate good through May 2024. In addition, these releases can be manually updated with a new certificate. Just put new files cdata.p12 and cdata.password into cTiVo's Support folder for the user running cTiVo: ~/Library/Application Support/com.ctivo.ctivo

Clone this wiki locally