Wiki Navigation

pyTivo Configuration

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 CurrentRelease page, will automatically generate a basic pyTivo.conf file for you.

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.

There are a few ExampleConf 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?

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

How Do I enable the Web configuration plugin?

Add the following lines to your pyTivo.conf file

[Admin]
type = admin

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
Individual Share Settings
Individual TiVo Settings

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. It is reported on Ubuntu that this port is already used so you may need to change it to something like port=9254.
Example Settings: 9032

guid

Default Setting: 123456
Valid Entries: Any 6 digit number
Required: Generally NO, will default to '123456' if left blank. If you use more than one pyTivo server on the same network a different random number is required here.
Skill: Advanced
Description: A unique identifier used in the beacon to identify this server. If you have 2 or more pyTivo servers on one network each server must use its own unique identifier.
Example Settings: Any 6 digit number.

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 seperated by a space
Required: No, defaults to 255.255.255.255
Skill: Advanced
Description: The beacon address which the beacon should broadcast on. Most people can leave this at the default setting. If set to listen will accept incoming TCP requests. Generally the default is fine, but if you are having issues with your shares not appearing on TiVo try taking the ip scheme of your network and change the last octet to 255. For example a network with a gateway of 192.168.1.1 would have a beacon address of 192.168.1.255. You can also specify the address of your TiVo or TiVos ie 192.168.1.150 192.168.1.151. If your shares still do not show up on the TiVo then something else is wrong.
Example Settings: 255.255.255.255 192.168.1.255

hack83

Default Setting: False
Valid Entries: True/False
Required: No
Skill: Moderate
Description: Available in the SubFoldersBranch. Allows TiVos with software 8.3 and above to display subfolders as users are accustomed to prior to the 8.3Software glitch. If you use this then you don't need to use auto_subshares. Warning: navigating folders too fast with this setting enabled may cause TiVo to reboot.
Example Settings: True/False

debug

Default Setting: False
Valid Entries: True/False
Required: No
Skill: Advanced
Description: Will create a file named debug.txt in the base folder of pyTivo. This file will contain debug information helpful in diagnosing problems. Generally only necessary if you are having a problem and the information is requested by support staff.
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.
Example Settings: True/False

audio_br

Default Setting: 192K for SD TiVo's, 384K for HD TiVo's
Valid Entries: Any valid Bit rate. Up to 384K for SD TiVos. Up to 448K for HD TiVos.
Required: No
Skill: Advanced
Description: This allows you to choose the default server audio bit rate used in transcoding. The default is likely fine for most users. Users with HD units and high quality videos to transcode will want to use 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: 192K, 384K, 448K.

max_audio_br

Default Setting: 448K
Valid Entries: Any valid Bit rate.
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 compatibilty.
Example Settings: 384K, 448K.

video_br

Default Setting: 4096K for SD TiVo's, 8192K for HD TiVo's
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.
Example Settings: 4096K, 8Mi, 12Mi

max_video_br

Default Setting: 17408k
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 mpeg's with a video bitrate above this setting will be transcoded rather than sent to the TiVo untouched. Raising this setting much higher than the default will likly result in pixelation during playback. 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

width

Default Setting: 544
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 Tivos, 720 for HD Tivos
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

ffmpeg_prams

Default Setting: -vcodec mpeg2video -r 29.97 -b %(video_br)s -maxrate %(max_video_br)s -bufsize %(buff_size)s %(aspect_ratio)s -comment pyTivo.py -ab %(audio_br)s %(audio_fr)s %(audio_codec)s -f vob -
Valid Entries: A valid ffmpeg command
Required: No
Skill: Very Advanced
Description: This allows you to control the parameters passed to ffmpeg. Most users will be just fine with the default setting. But since HD Tivos will play any framerate, you may want to remove -r 29.97 if you have a HD Tivo to eliminate the jitter sometimes introduced by changing frame rate. Example Settings: See Above and the forum.

%(audio_fr)s

Default Setting: -ar 48000
Valid Entries: -ar 44100, -ar 48000
Required: No
Skill: Very 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. This setting cannot be defined as a separate parameter in the config like the other settings. But you may override the pyTivo settings by removing or replacing %(audio_fr)s in your ffmpeg_prams line with one of the example settings.
Example Settings: -ar 44100, -ar 48000

%(audio_codec)s

Default Setting: "-acodec mp2 -ac 2" for S2, "-acodec ac3" for S3/HD
Valid Entries: any TiVo compatible codec supported by ffmpeg
Required: No
Skill: Very Advanced
Description: Sets the audio codec used by pyTivo. pyTivo checks the audio codec and bitrate of the source and uses -acodec copy if it is compatible. Otherwise the Default Setting is used. This setting cannot be defined as a separate parameter in the config like the other settings. But you may override the pyTivo settings by replacing %(audio_codec)s in your ffmpeg_prams line.
Example Settings: "-acodec mp2 -ac 2", "-acodec ac3"

bufsize

Default Setting: 1024k
Valid Entries: Any valid byte size
Required: No
Skill: Very Advanced
Description: Allows you to set the buffer size used by ffmpeg. I don't know much about this setting, but from what I can tell it is rather touchy and should only be edited by advanced users.
Example Settings: 1024k

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, 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 or music

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

auto_subshares

Default Setting: false
Valid Entries: True/False
Required: No
Skill: Moderate
Description: Subfolders of the share paths you define will be seen by pyTivo and displayed as subfolders in the Now Playing List. This is an alternative to the hack83 setting which enables the SubFoldersBranch
Example Settings: True/False

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

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 mos users will not have to mess with this.
Example Settings: True/False

audio_br

Default Setting: Defaults to whatever is in Server section or the default described in the server section
Valid Entries: Any valid bit rate.
Required: No
Skill: Advanced
Description: Overrides the same setting in the Server section for this specific TiVo. Useful if you have both S2 and HD units.
Example Settings: See above.

max_audio_br

Default Setting: Defaults to whatever is in Server section or the default described in the server section
Valid Entries: Any valid Bit rate.
Required: No
Skill: Advanced
Description: Overrides the same setting in the Server section for this specific TiVo. Useful if you have both S2 and HD units.
Example Settings: See above.

video_br

width

Default Setting: Defaults to whatever is in Server section or the default described in the server section
Valid Entries: Any valid pixel dimension.
Required: No
Skill: Advanced
Description: Overrides the same setting in the Server section for this specific TiVo. Useful if you have both S2 and HD units.
Example Settings: See above.

height

ffmpeg_prams

Default Setting: Defaults to whatever is in Server section or the default described in the server section
Valid Entries: Any valid ffmpeg parameters.
Required: No
Skill: Very Advanced
Description: Overrides the same setting in the Server section for this specific TiVo. Useful if you have both S2 and HD units.
Example Settings: See above.

Default Setting: Blank, which is equivalent to allow all shares on this TiVo.
Valid Entries: The name of any share in your pyTivo.conf file. A comma separated list.
Required: No
Skill: Easy
Description: Only the shares listed in this setting will be visible on this TiVo. Will ignore invalid shares. If no valid shares are listed or the setting does not exist, all shares will be visible on this TiVo.
Example Settings: Movies, Kids Stuff

Download in other formats:

Plain Text