Configure pyTivo

From pyTivo - Wiki

(NOTE: This section is sometimes outdated and certain forks do not include all settings. See the web admin within your version to see the latest configuration options and recommendations. See below for instructions on how to access the web admin.)

All settings are contained in the pyTivo.conf file in the base directory. A commented example is distributed with pyTivo under the file name pyTivo.conf.dist. (note the different names.) Do NOT attempt to just rename pyTivo.conf.dist and use it. Read the following information and create your version of pyTivo.conf accordingly. The Windows Installer, available on the Current Releases page, will automatically generate a basic pyTivo.conf file for you.

Contents 1 What do I need to edit for pyTivo to work? 2 About the file format 3 How Do I edit the pyTivo.conf file? 4 Settings 4.1 Server Settings 4.1.1 port 4.1.2 ffmpeg 4.1.3 beacon 4.1.4 debug 4.1.5 optres 4.1.6 par 4.1.7 video_fps 4.1.8 video_br 4.1.9 video_pct 4.1.10 max_video_br 4.1.11 bufsize 4.1.12 width 4.1.13 height 4.1.14 audio_br 4.1.15 max_audio_br 4.1.16 audio_fr 4.1.17 audio_ch 4.1.18 audio_codec 4.1.19 audio_lang 4.1.20 copy_ts 4.1.21 ffmpeg_pram 4.1.22 ffmpeg_tmpl 4.1.23 ffmpeg_wait 4.1.24 tivo_mak 4.1.25 togo_path 4.2 Individual Share Settings 4.2.1 type 4.2.2 path 4.2.3 precache 4.2.4 force_alpha 4.3 Individual TiVo Settings 4.3.1 aspect169 4.3.2 shares

What do I need to edit for pyTivo to work?

• You need to have a valid [Server] section with all the required settings. For the [Server] section these are:
  • port and ffmpeg
• Plus you need at least one share.
  • This share must have a valid name i.e. [Videos] or [Music] or [Movies] <> characters cannot be in the share name
  • All the required share settings. These are:
    • type and path
  • You can define as many shares as you wish.
• If you would like to use the ToGo features of pyTivo on port 9032 of a web browser you will need to add a few extra items as follows:
  • tivo_mak=nnnnnnnnn (This is your Tivo Media Access Key)
  • togo_path=(Path where you want pulled items will be stored locally)
    • Note this is a location on your pyTivo running LOCAL Machine. It can be a NAS location.

There are a few example conf files available to aid you.

About the file format

• Names in square brackets (e.g., [Server]) start a "Section". A section continues until the next section name or the end of the file, whichever comes first.
• The '#' (pound sign) comments out everything following it on a line. pyTivo ignores commented text -- it is there only to clarify things for the reader.
• Each line in a section defines a parameter in that section. The form is <key>=<value>

How Do I edit the pyTivo.conf file?

1. Any text editor can open and edit the pyTivo.conf file.
2. There's also a Web Configuration plugin. This is accessible from the server at http://localhost:9032/

Settings

Below is what I believe to be a comprehensive list and the accompanying descriptions of what the settings do:

Server Settings

port

Default Setting: None, must be entered. Distributed conf file uses 9032
Valid Entries: Valid port number
Required: Yes, without a port setting in the conf file pyTivo will not start.
Skill: Basic
Description: The port which pyTivo uses to serve your files. Can be changed if it conflicts with another program.
Example Settings: 9032

ffmpeg

Default Setting: There is none.
Valid Entries: Operating system path
Required: Yes
Skill: Basic
Description: This is the full path to your ffmpeg binary. For Windows users ffmpeg is distributed with pyTivo and is in the plugins/video folder.
Example Settings: __Linux__ = /usr/bin/ffmpeg | __Windows__ = c:\Program Files\pyTivo\plugins\video\ffmpeg_mp2.exe

beacon

Default Setting: 255.255.255.255
Valid Entries: Beacon IP address(es) or "listen". Can contain multiple IPs separated by spaces.
Required: No
Skill: Advanced
Description: The addresses on which the beacon should broadcast. Most people can leave this at the default. If set to "listen", will accept incoming TCP beacons. If you're having issues with your shares not appearing on TiVo, try using the broadcast address of your LAN. For example, if your gateway (router) used address 192.168.1.1, your broadcast address would be 192.168.1.255. Alternatively, you can specify the exact addresses of your TiVos, e.g. 192.168.1.150 192.168.1.151.
Example Settings: 192.168.1.255

debug

Default Setting: False
Valid Entries: True/False
Required: No
Skill: Advanced
Description: Will generate more output for debugging purposes.
Example Settings: True/False

optres

Default Setting: False
Valid Entries: True/False
Required: No
Skill: Moderate
Description: Allows for the use of the Optimal Resolution in transcoding. By setting optres = true pyTivo will treat the height and width settings in the conf file as a maximum. If the video to be transcoded has smaller dimensions that are closer to other acceptable TiVo dimensions then pyTivo will use these dimensions. This allows for faster transcoding and small files when the initial video is a lower quality. pyTivo uses the same resolution as the source file on HD TiVos for optimal transcoding efficiency. It is not necessary to to set this option with HD TiVos unless you wish to force pyTivo to change the resolution to an "S2 compatible" resolution.
Example Settings: True/False

par

Default Setting: 1.0
Valid Entries: any valid par
Required: No
Skill: Very Advanced
Description: Set pixel aspect ratio. Applies to S3 Tivos only. OPTRES must be false to use PAR. For some videofiles (e.g., AVC files), ffmpeg cannot determine the pixel aspect ratio correctly and assumes 1:1 which leads to a distorted image on anamorphically encoded video files. This setting allows you to override this default. If you do not understand this setting, and you observe no distortions, you can ignore it. Set par=1.0 to tell pyTivo to automatically adjust the pixel aspect ratio whenever possible.

par=1.18518519 (32:27, usually the correct setting for wide-screen anamorphically encoded DVD content)

par=0.88888889 (8:9, usually the correct setting for anamorphically encoded DVDs from TV shows)
Example Settings: 1.0, 1.18518519, 0.88888889
Alternative option: Specify par in metadata txt files by adding "Override_par : x.xxxx" to a metadata file associated with the video file. If all files in the folder have the same par, add the option to a file called default.txt instead of creating individual metadata files.

video_fps

Default Setting: 29.97 for S2 TiVo, same as source for S3/HD TiVo
Valid Entries: 29.97, 23.98, 25, 59.94
Required: No
Skill: Advanced
Description: Sets the frame rate used by ffmpeg. pyTivo uses 29.97 for S2's, and uses the same frame rate as the source on HD TiVos. The default setting should work fine for most transfers.
Example Settings: 29.97, 23.98, 25, 59.94

video_br

Default Setting: 4096K for SD TiVos, 16384K for HD TiVos
Valid Entries: Any valid Bit rate. 1024K = 1Mi
Required: No
Skill: Advanced
Description: This allows you to choose the default server video bit rate used in transcoding. FFmpeg does not strictly follow this bit rate, there is a certain level of tolerance that is allowed. Also a low quality file will always have a low bit rate. The default is likely fine for most users. Higher values may slow down transcoding and will increase the file size. Increased file sizes take up more room on the TiVo and take longer to transfer over the network. (Higher settings are recommended for screen sizes above 47" such as: video_br=20Mi, width=1920, height=1080)
Example Settings: 4096K, 8Mi, 12Mi, 16Mi, 20Mi

video_pct

Default Setting: 85 (percent of source bitrate)
Valid Entries: Any number (set this to 0 to disable this option)
Required: No
Skill: Advanced
Description: This sets video_br to a percent of the source video bitrate. pyTivo will multiply the source video bitrate by this percentage setting, compare it to the video_br setting and use whichever is greater as the video_br. This allows for setting higher bitrates automatically when transcoding High Definition sources. For example, if your source file has a bitrate of 22000k and video_pct is set to 70, pyTivo will use 15400k for video_br instead of the default 8192k setting. With this setting enabled, the video_br setting essentially becomes the minimum video bitrate. This setting only applies to S3 tivos.
Example Settings: 60, 70, 85, 100, 125

max_video_br

Default Setting: 30000k
Valid Entries: Any valid Bit rate. 1024K = 1Mi
Required: No
Skill: Advanced
Description: This allows you to choose the maximum bit rate and is more strict than the video_br setting above. However setting this can cause buffer overflows and can cause issues with ffmpeg. In addition to setting the ffmpeg maxrate option, this setting is used to determine if the video bitrate of the source video file is too high for the TiVo. Otherwise compatible mpegs with a video bitrate above this setting will be transcoded rather than sent to the TiVo untouched. Lower this setting below the bitrate of your source file if you wish to force high bitrate sources to be transcoded. Recommended only for skilled users. Note: there is a report that ffmpeg throws an error with 17Mi but accepts 17408K just fine.
Example Settings: 17408k, 30000k

bufsize

Default Setting: 1024k for S2, 4096k for S3
Valid Entries: Any valid byte size
Required: No
Skill: Very Advanced
Description: Allows you to set the buffer size used by ffmpeg. Increasing this setting will allow higher bitrates during transcoding (see video_br setting), especially when transcoding to HD resolutions. But it may result in pixelation or audio sync issues with some sources. 1024k is fine for the resolutions used by S2 tivos. But 2048k or 4096k is preferred for HD tivos. Leave this setting blank unless you are experiencing audio/video sync issues and wish to test a different value.
Example Settings: 1024k, 2048k, 4096k

width

Default Setting: 544 for S2, 1280 for S3
Valid Entries: Any valid pixel dimension. Setting will be rounded to nearest acceptable TiVo dimension.
Required: No
Skill: Moderate
Description: Allows you to choose the output dimension of the transcoded videos. SD units are limited to 720 and below. Likely HD users will want to choose a higher value. Higher values may slow down transcoding and will increase the file size. Increased file sizes take up more room on the TiVo and take longer to transfer over the network.
Example Settings: 1920, 1440, 1280, 720, 704, 544, 480, 352.

height

Default Setting: 480 for S2, 720 for S3
Valid Entries: Any valid pixel dimension. Setting will be rounded to nearest acceptable TiVo dimension
Required: No
Skill: Moderate
Description: Allows you to choose the output dimension of the transcoded videos. SD units are limited to 480 and below. Likely HD users will want to choose a higher value. Higher values may slow down transcoding and will increase the file size. Increased file sizes take up more room on the TiVo and take longer to transfer over the network.
Example Settings: 1080, 720, 480

audio_br

Default Setting: Same bitrate as source or 448k
Valid Entries: Any valid bitrate up to 448k
Required: No
Skill: Advanced
Description: This allows you to choose the default audio bit rate used for transcoding. The default is likely fine for most users. 384k is the minimum recommended for ac3 audio. For S2 TiVos, you may want to lower this setting to 192k and set audio_ch=2 to slightly reduce the file size. See audio_codec for more info.
Example Settings: 192K, 384K, 448K.

max_audio_br

Default Setting: 448K
Valid Entries: Any valid bitrate
Required: No
Skill: Advanced
Description: This sets the maximum audio bit rate that can be sent to the TiVo. Files having a higher bit rate will be transcoded to ensure TiVo compatibility.
Example Settings: 384K, 448K

audio_fr

Default Setting: same frequency as source
Valid Entries: 44100, 48000
Required: No
Skill: Advanced
Description: Sets the audio sampling frequency. Defaults to frequency of the source file for better audio sync if it is 44100 or 48000. Otherwise 48000 is used.
Example Settings: 44100, 48000

audio_ch

Default Setting: same channels as source
Valid Entries: any number compatible with ffmpeg and the audio codec selected
Required: No
Skill: Advanced
Description: Sets the number of audio channels used by ffmpeg. ffmpeg will retain the same number of channels as the source file by default. The default setting should work fine for most transfers unless the default audio_codec is changed. Change this setting to 2 if you do not want to retain 5.1 audio. A bug in ffmpeg will sometimes move the center audio channel to the left or right speaker. Setting this option to 2, on an as needed basis, or permanently, will correct this at the loss of 5.1 audio. But this should only be necessary on rare occasions where the source file is an mkv or xvid with ac3 5.1 audio bitrate above 448k.
Example Settings: 2, 6

audio_codec

Default Setting: ac3 or copy
Valid Entries: mp2, ac3
Required: No
Skill: Advanced
Description: Sets the audio codec used by ffmpeg during transcoding. pyTivo defaults to ac3 in order to retain 5.1 audio should the source contain it. pyTivo also checks the audio codec and bitrate of the source and uses '-acodec copy' if it is compatible. Otherwise the Default Setting is used. Specifying an audio codec will disable these features and pyTivo will re-encode all audio using the codec specified.

Allowing pyTivo to select '-acodec copy' whenever possible will generally produce the best results. This is meant to eliminate garbled audio during transcoding when the source contains audio glitches that cause ffmpeg to lose synchronization. This will also prevent the center audio channel from being moved to the right front speaker by ffmpeg when transferring mkv's and xvid's with audio bitrate of 448k or less.

You may want to change this setting to mp2 if you only have an S2, or have specified a per tivo section for an S2, and do not wish to retain 5.1 audio for possible transfer to an S3 Tivo or back to the PC should the need arise. This will slightly reduce the amount of disk space used and allow for more recordings on an S2 Tivo. In this case, you will want to specify audio_codec=mp2, audio_ch=2, and audio_br=192k. These are the settings normally used by the S2 for recordings.
Example Settings: mp2, ac3

audio_lang

Recommended Setting: 5.1, DTS, en (entire string including commas)
pyTivo Defaults To: first audio stream
Valid Entries: any language tag or audio stream number reported by ffmpeg
Required: No
Skill: Basic
Description: Sets the preferred language track used by pyTivo. ffmpeg/pytivo defaults to the first audio stream. Specifying this parameter, tells pyTivo to use the first audio stream that matches this entry if more than one audio stream exists. If your video source does not have language tags, you may specify the audio stream number reported by ffmpeg (ie. 0.1, 0.2 ect.). Stream references like 0x80, 0x81, etc. may also be specified. pyTivo will transcode the file if necessary to obtain the preferred language track.

You can also assign new language tags to your files by adding Override lines to your metadata txt files. This will enable pytivo to detect your audio language setting in files that do not contain language tags. The syntax is
Override_mapAudio 0.1 colon eng (replace the word colon with a colon)
Where 0.1 is the audio stream number reported by ffmpeg and eng is the new audio tag to assign to that stream. Add a separate Override line for each audio stream that you want to replace with a new tag.
Example Settings: eng, ger, spa, en, ge, 0.0, 0.1, 0.2, 0x80, 0x81 etc...

copy_ts

Default Setting: True
Valid Entries: True/False
Required: No
Skill: Basic
Description: Adds the copy timestamps setting (-copyts) to the ffmpeg command. This setting helps correct audio synchronization problems that commonly occur during transcoding. You can leave this field blank unless you wish to disable it. pyTivo defaults to True except when pyTivo uses acodec copy, in which case copyts is not needed, and a conflict could also occur if the source file has really corrupt sections.
Example Settings: True, False

ffmpeg_pram

Default Setting: blank
Valid Entries: A valid ffmpeg command
Required: No
Skill: Very Advanced
Description: This allows you to append additional raw ffmpeg commands to the ffmpeg template. For example, you would enter '-threads 2' here if you have multiple processors and want ffmpeg to use both processors to speed up transcoding.
Example Settings: -threads 2

ffmpeg_tmpl

Default Setting: %(video_codec)s %(video_fps)s %(video_br)s %(max_video_br)s %(buff_size)s %(aspect_ratio)s %(audio_br)s %(audio_fr)s %(audio_ch)s %(audio_codec)s %(audio_lang)s %(ffmpeg_pram)s %(format)s
Valid Entries: A valid ffmpeg command
Required: No
Skill: Very Advanced
Description: This is a template used by pyTivo to control the parameters passed to ffmpeg. It should not be necessary to modify this template unless there is a particular parameter you do not wish ffmpeg to use and it cannot be overridden by specifying that parameter in the pyTivo.conf file.
Example Settings: See Above and the forum.

ffmpeg_wait

Default Setting: 10 (seconds)
Valid Entries: any integer
Required: No
Skill: Advanced
Description: Slow computers or NAS servers may result in pytivo reporting supported videos as not supported (copy protected). Increasing this setting will give ffmpeg more time to scan the file.
Example Settings: 10, 15, 20.

tivo_mak

Default Setting: NONE
Valid Entries: an integer
Required: No
Skill: Basic
Description: This is used along with togo_path, to allow pulls using the http port 9032 interface in pyTivo. This is your Media Access Key, which you can obtain from your Tivo under System information
Example Settings: 123456789.

togo_path

Default Setting: NONE
Valid Entries: any valid LOCAL path
Required: No
Skill: Basic
Description: This is used along with tivo_mak, to allow pulls using the http port 9032 interface in pyTivo. This is the location where pulled files are stored on the machine running pyTivo. This CAN be a path on a NAS or shared drive.
Example Settings: __Windows__ = C:\pulledtivo | __Linux__ = /home/user/pulledtivo

Individual Share Settings

These sections create the shares that are visible in the Now Playing List. The name used in these sections is the name used in the NPL. Therefore [Videos] will show up as videos in your NPL.

type

Default Setting: None
Valid Entries: video, music, photo, or any other valid plugin name.
Required: Yes
Skill: Basic
Description: Sets the type of share that this will be. This must be set to something otherwise pyTivo will not start. Plugin names are generally all lower case.
Example Settings: video, music, photo

path

Default Setting: None
Valid Entries: Any operating system path
Required: Yes
Skill: Basic
Description: Sets the base path to your media content. While pyTivo will start with an invalid path your shares will not work at all.
Example Settings: __Windows__ = C:\videos | __Linux__ = /home/user/media

precache

Default Setting: False
Valid Entries: True/False
Required: No
Skill: Moderate
Description: In order to verify that the video files present on your computer were compatible with ffmpeg in older versions pyTivo would query ffmpeg for each file. While this information was cached it still caused a delay in the initial loading of a list of files. This precache setting forced pyTivo to inspect each video prior to starting the pyTivo server. However, this had two drawbacks. 1. It took time as much as two minutes before pyTivo was ready to accept requests. 2. It did not update the cache if new files were added while the pyTivo server was running.
In the more recent releases, anything after Feb 16, 2008, pyTivo no longer needs to query ffmpeg when creating a file list. Instead pyTivo has a list of accepted video format extensions. If the file extension falls within this list it is displayed on the TiVo. This achieves the same speed increase as the precache method without the delay in loading the pyTivo server.
There are still two drawbacks to this method. 1. The video file must have an extension that is in the list. There is a possibility that a new video file extension could come out before pyTivo is updated. 2. Incomplete or video files with errors will still appear in the TiVo listing if they have the correct extension, even though they are not valid files. Both of these concerns are minimal. 1. Very few new formats of video files come out very often. And all extensions are stored in the video.ext file which is easily edited. 2. When viewing the file details before transferring the pyTivo server queries ffmpeg to make sure it is valid. If the file is not valid it will show up as a copyrighted file and transferring it will be prevented by TiVo.
It is recommended that you leave precaching turned off as it is no longer needed.
Example Settings: True/False

force_alpha

Default Setting: False
Valid Entries: True/False
Required: No
Skill: Basic
Description: This will override the sort order of a video share and force sorting to be alphabetical, with folders appearing first. This ONLY works on video shares. See this post for a discussion.
Example Settings: True/False

Individual TiVo Settings

These settings affect individual TiVo units. Settings in this section will override the default and global server settings for this specific TiVo. This is useful if you have both SD and HD TiVo units. The section name used for this look like [_tivo_24000000DEADBEEF]. The number appended to _tivo_ is the TSN (TiVo Service Number), which is found in the System Information screen of the TiVo unit.

aspect169

Default Setting: True
Valid Entries: True/False
Required: No
Skill: Moderate
Description: Most TiVos, even S2, can handle 16:9 videos perfectly. Some S2s are known not to handle 16:9 and will default to false in this setting. If you are experiencing major distortion you can try setting this to false. Likely most users will not have to mess with this.
Example Settings: True/False

shares

Valid Entries: The names of any shares in your pyTivo.conf file, in a comma-separated list. Having a blank entry will show NO shares in this tivo. IE hide all video shares.
Required: No
Skill: Easy
Description: Only the shares listed in this setting will be visible on this TiVo. Will ignore invalid shares. If the setting does not exist, all shares will be visible on this TiVo. If the setting exists but the list is blank, NO shares will be shown. IE Shares =
Example Settings: Movies, Kids Stuff