help file updates

[pyTivo/wgw.git] / plugins / admin / help.txt

###################### pyTivo Web Admin Help #########################\r
#\r
# Description: This file contains the information displayed in the  \r
# settings help section of the web admin. Most users will never need  \r
# to edit or view this file\r
#\r
# Format: Blank lines and lines beginning with # are ignored. \r
# The name of a section should appear on its own line and should NOT\r
# contain a colon.  Subsequent lines should contain the portion to be\r
# bolded, followed by a colon, followed by the descriptive text all on\r
# ONE line. Each line will be read into the previously named section  \r
# until a line is reached which does not contain a colon or the EOF is \r
# reached. Lines ending in <br><br>+\ will be concated with the next lines \r
#\r
# SPECIAL SECTION: In order for the web plugin to know which settings\r
# are available. To do this the follow line should be present in\r
# every setting:\r
#\r
# Available In:\r
#\r
# This entry should be a comma seperated list of the sections which \r
# this setting should be shown in. For example:\r
#\r
# Available In: Server, TiVos, Shares\r
#\r
######################################################################\r
\r
port\r
\r
Default Setting: None, must be entered. Distributed conf file uses 9032\r
Valid Entries: Valid port number\r
Required: Yes, without a port setting in the conf file pyTivo will not start.\r
Skill: Basic\r
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.\r
Example Settings: 9032\r
Available In: Server\r
\r
guid\r
\r
Default Setting: 123456\r
Valid Entries: Any 6 digit number\r
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.\r
Skill: Advanced\r
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.\r
Example Settings: Any 6 digit number.\r
Available In: Server\r
\r
ffmpeg\r
\r
Default Setting: There is none.\r
Valid Entries: Operating system path\r
Required: Yes!\r
Skill: Basic\r
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\r
Example Settings: Linux = /usr/bin/ffmpeg | Windows = c:\Program Files\pyTivo\plugins\video\ffmpeg_mp2.exe\r
Available In: Server\r
\r
beacon\r
\r
Default Setting: 255.255.255.255\r
Valid Entries: A Subnet or Listen\r
Required: No, defaults to 255.255.255.255\r
Skill: Advanced\r
Description: The subnet which the beacon should broadcast on. Most people can leave this at the default setting. If set to listen will accept incoming TCP requests.\r
Example Settings: 255.255.255.255\r
Available In: Server\r
\r
hack83\r
\r
Default Setting: False\r
Valid Entries: True/False\r
Required: No\r
Skill: Moderate\r
Description: Available in the SubFoldersBranch. Allows TiVos with software 8.3 and above to display subfolders as users are accustomed too 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.\r
Example Settings: True/False\r
Available In: Server\r
\r
debug\r
\r
Default Setting: False\r
Valid Entries: True/False\r
Required: No\r
Skill: Advanced\r
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.\r
Example Settings: True/False\r
Available In: Server\r
\r
precache\r
\r
Default Setting: false\r
Valid Entries: True/False\r
Required: No\r
Skill: Moderate\r
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.<br><br>+\\r
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.<br><br>+\\r
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.<br><br>+\\r
It is recommended that you leave precaching turned off as it is no longer needed.\r
Example Settings: True/False\r
Available In: Shares\r
\r
optres\r
\r
Default Setting: False\r
Valid Entries: True/False\r
Required: No\r
Skill: Moderate\r
Description: Allows for the use of the Optimal Resolution in transcoding. By setting optes = 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 necessay to to set this option with HD TiVos unles you wish to force pyTivo to change the resolution to an "S2 compatible" resolution.\r
Example Settings: True/False\r
Available In: Server, Tivos\r
\r
par\r
\r
Recommended Setting: 1.0\r
pyTivo Defaults To: blank\r
Valid Entries: any valid par\r
Required: No\r
Skill: Very Advanced\r
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.<br><br>+\\r
par=1.18518519 (32:27, usually the correct setting for wide-screen anamorphically encoded DVD content)<br><br>+\\r
par=0.88888889 (8:9, usually the correct setting for anamorphically encoded DVDs from TV shows)\r
Example Settings: 1.0, 1.18518519, 0.88888889\r
Available In: Server\r
\r
video_fps\r
\r
Recommended Setting: blank\r
pyTivo Defaults To: 29.97 for S2 Tivo, same as source for S3/HD TiVo\r
Valid Entries: 29.97, 23.98, 25, 59.94\r
Required: No\r
Skill: Advanced\r
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.\r
Example Settings: 29.97, 23.98, 25, 59.94\r
Available In: Server, Tivos\r
\r
video_br\r
\r
Default Setting: 4096K for SD TiVo's, 8192K for HD TiVo's\r
Valid Entries: Any valid Bit rate. 1024K = 1Mi\r
Required: No\r
Skill: Advanced\r
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.  See the bufsize setting if you increase this setting to 12Mi or above for transcoding to 1080 resolutions.\r
Example Settings: 4096K, 8Mi, 12Mi, 16Mi\r
Available In: Server, Tivos\r
\r
video_pct\r
\r
Recommended Setting: blank\r
pyTivo Defaults to: 70 (percent of source bitrate)\r
Valid Entries: Any number (set this to 0 to disable this option)\r
Required: No\r
Skill: Advanced\r
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.\r
Example Settings: 60, 70, 85, 100\r
Available In: Server\r
\r
max_video_br\r
\r
Recommended Setting: blank\r
pyTivo Defaults to: 30000k\r
Valid Entries: Any valid Bit rate. 1024K = 1Mi\r
Required: No\r
Skill: Advanced\r
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. mpeg's 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.\r
Example Settings: 17408k, 30000k\r
Available In: Server\r
\r
bufsize\r
\r
Recommended Setting: 4096k\r
pyTivo Defaults To: 1024k\r
Valid Entries: Any valid byte size\r
Required: No\r
Skill: Very Advanced\r
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 you will probably want to increase this setting to 2048k or 4096k if you have an HD tivo.\r
Example Settings: 1024k, 2048k, 4096k\r
Available In: Server\r
\r
width\r
\r
Default Setting: 544 for S2, 1280 for S3\r
Valid Entries: Any valid pixel dimension. Setting will be rounded to nearest acceptable TiVo dimension\r
Required: No\r
Skill: Moderate\r
Description: Allows you to choose the output dimension of the transcoded videos. SD units are limited to 544 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.\r
Example Settings: 1920, 1440, 1280, 720, 704, 544, 480, 352.\r
Available In: Server, Tivos\r
\r
height\r
\r
Default Setting: 480 for S2, 720 for S3\r
Valid Entries: Any valid pixel dimension. Setting will be rounded to nearest acceptable TiVo dimension\r
Required: No\r
Skill: Moderate\r
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.\r
Example Settings: 1080, 720, 480\r
Available In: Server, Tivos\r
\r
audio_br\r
\r
Recommended Setting: blank\r
pyTivo Defaults To: same bitrate as source or 384k\r
Valid Entries: Any valid Bit rate up to 448k.\r
Required: No\r
Skill: Advanced\r
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.\r
Example Settings: 192K, 384K, 448K.\r
Available In: Server, Tivos\r
\r
max_audio_br\r
\r
Recommended Setting: blank\r
pyTivo Defaults To: 448k\r
Valid Entries: Any valid Bit rate.\r
Required: No\r
Skill: Advanced\r
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.\r
Example Settings: 384K, 448K.\r
Available In: Server, Tivos\r
\r
audio_fr\r
\r
Recommended Setting: blank\r
pyTivo Defaults To: same frequency as source\r
Valid Entries: 44100, 48000\r
Required: No\r
Skill: Advanced\r
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.\r
Example Settings: 44100, 48000\r
Available In: Server, Tivos\r
\r
audio_ch\r
\r
Recommended Setting: blank\r
pyTivo Defaults To: same channels as source\r
Valid Entries: any number compatible with ffmpeg and the audio codec selected\r
Required: No\r
Skill: Advanced\r
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.\r
Example Settings: 2, 6\r
Available In: Server, Tivos\r
\r
audio_codec\r
\r
Recommended Setting: blank\r
pyTivo Defaults To: ac3 or copy\r
Valid Entries: mp2, ac3\r
Required: No\r
Skill: Advanced\r
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.<br><br>+\\r
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.<br><br>+\\r
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.\r
Example Settings: mp2, ac3\r
Available In: Server, Tivos\r
\r
audio_lang\r
\r
Recommended Setting: eng\r
pyTivo Defaults To: blank\r
Valid Entries: any language tag or audio stream number reported by ffmpeg\r
Required: No\r
Skill: Basic\r
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.<br><br>+\\r
Example Settings: eng, ger, spa, en, ge, 0.0, 0.1, 0.2, 0x80, 0x81 etc...\r
Available In: Server, Tivos\r
\r
\r
copy_ts\r
\r
Recommended Setting: blank\r
pyTivo Defaults To: True\r
Valid Entries: blank, True, False\r
Required: No\r
Skill: Basic\r
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.<br><br>+\\r
Example Settings: blank, True, False\r
Available In: Server, Tivos\r
\r
ffmpeg_pram\r
\r
Default Setting: blank\r
Valid Entries: A valid ffmpeg command\r
Required: No\r
Skill: Very Advanced\r
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.\r
Example Settings: -threads 2\r
Available In: Server, Tivos\r
\r
ffmpeg_tmpl\r
\r
Recommended Setting: blank\r
pyTivo Defaults To: %(video_codec)s %(video_fps)s %(video_br)s %(max_video_br)s %(buff_size)s %(aspect_ratio)s -comment pyTivo.py %(audio_br)s %(audio_fr)s %(audio_ch)s %(audio_codec)s %(ffmpeg_pram)s %(format)s\r
Valid Entries: A valid ffmpeg command\r
Required: No\r
Skill: Very Advanced\r
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.\r
Example Settings: See Above and the forum.\r
Available In: Server, Tivos\r
\r
type\r
\r
Default Setting: None\r
Valid Entries: video, music, or any other valid plugin name.\r
Required: Yes\r
Skill: Basic\r
Description: Sets the type of share that this will be. This must be set to something otherwise pyTivo will not start. NOTE plugins names are generally lowercase.\r
Example Settings: video, music\r
Available In: Shares\r
\r
path\r
\r
Default Setting: None\r
Valid Entries: Any operating system path\r
Required: Yes\r
Skill: Basic\r
Description: Sets the base path to your media content. While pyTivo will start with an invalid path your shares will not work at all.\r
Example Settings: Windows = C:\videos | Linux = /home/user/media\r
Available In: Shares\r
\r
auto_subshares\r
\r
Default Setting: false\r
Valid Entries: True/False\r
Required: No\r
Skill: Moderate\r
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\r
Example Settings: True/False\r
Available In: Shares\r
\r
aspect169\r
\r
Default Setting: True\r
Valid Entries: True/False\r
Required: No\r
Skill: Moderate\r
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.\r
Example Settings: True/False\r
Available In: Tivos\r
\r
shares\r
\r
Default Setting: Blank, which is equivalent to allow all shares on this TiVo.\r
Valid Entries: The name of any share in your pyTivo.conf file. A comma separated list.\r
Required: No\r
Skill: Easy\r
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.\r
Example Settings: Movies, Kids Stuff\r
Available In: Tivos\r
\r
\r
\r