New format for Override_mapAudio, needed to support newer FFmpeg.

[pyTivo/wmcbrine.git] / plugins / settings / 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.\r
# Each line will be read into the previously named section until a\r
# blank line or the EOF is reached. Lines containing colons that\r
# don't mark a new subhead must be escaped by placing '>' in the\r
# first position.\r
#\r
# In order for the web config plugin to know which settings are \r
# available in which sections, the following line should be present in \r
# each 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, HD_tivos, SD_tivos, Shares\r
#\r
######################################################################\r
\r
Instructions\r
\r
To Edit a Share: Select the share in the left hand menu.\r
To Delete a Share: Select the share in the left hand menu and click \r
delete.\r
To Add a Share/Tivo/Section: Click the "Add Section" button.  Then \r
provide the name of the share or TiVo. You must save your changes before \r
you can edit settings in the new share.\r
To Add a Setting: Select your share first.  If the setting is a known \r
setting simply add the value to the appropriate setting. If the setting \r
is not listed you can add a "User Defined Setting".  Simple click add \r
setting and provide the name and value of this new setting.\r
To Delete a Setting: Delete the value of the setting so that it is \r
blank.  If this is a known share the name will remain after a save. If \r
the setting is a user defined setting the name will be deleted after the \r
save.\r
Save Settings: Clicking Save Settings will write your changes to the \r
pyTivo.conf file. These settings may not have an effect on your pyTivo \r
server until it is Soft Reset or restarted.\r
Soft Reset: Soft Reset allows most new settings to take effect without \r
restarting pyTivo.  The Soft Reset will cause a re-read of the\r
pyTivo.conf file so your changes must be saved to the file before the\r
reset.\r
\r
Add_a_New_Section\r
\r
Add the name of a new section: If you want to add a TiVo section, \r
remember it must start with "_tivo_". You must save your settings before \r
the new section will be editable.\r
\r
port\r
\r
Default Setting: 9032\r
Valid Entries: 1-65535\r
Required: No\r
Description: The port which pyTivo uses to serve your files. Can be\r
changed if it conflicts with another program.\r
Example Settings: 9032\r
Available In: Server\r
\r
ffmpeg\r
\r
Default Setting: None\r
Valid Entries: Operating system path\r
Required: No\r
Description: This is the full path to your ffmpeg binary. If not set, \r
pyTivo checks for it in a "bin" subdirectory, and then in the PATH. If \r
no ffmpeg is found, pyTivo will operate in a limited mode, serving only \r
MPEG and TiVo files in video shares, and only MP3 files in music shares, \r
with no seek capability.\r
Example Settings: Linux = /usr/bin/ffmpeg |\r
>Windows = C:\pyTivo\bin\ffmpeg.exe\r
Available In: Server\r
\r
tivodecode\r
\r
Default Setting: None\r
Valid Entries: Operating system path\r
Required: No\r
Description: This is the full path to your tivodecode binary. If not \r
set, pyTivo checks for it in a "bin" subdirectory, and then in the PATH.\r
tivodecode is only needed for certain functions (currently pushing .TiVo \r
files or transcoding HD .TiVo files to SD).\r
Example Settings: Linux = /usr/bin/tivodecode |\r
>Windows = C:\pyTivo\bin\tivodecode.exe\r
Available In: Server\r
\r
tdcat\r
\r
Default Setting: None\r
Valid Entries: Operating system path\r
Required: No\r
Description: This is the full path to your tdcat binary. If not set, \r
pyTivo checks for it in a "bin" subdirectory, and then in the PATH. \r
tdcat is only needed to view the data from a .TiVo file in the details \r
screen. It comes with tivodecode.\r
Example Settings: Linux = /usr/bin/tdcat |\r
>Windows = C:\pyTivo\bin\tdcat.exe\r
Available In: Server\r
\r
beacon\r
\r
Default Setting: 255.255.255.255\r
Valid Entries: Beacon IP address(es) or "listen".  Can contain multiple\r
IPs separated by spaces.\r
Required: No\r
Description: The addresses on which the beacon should broadcast.  Most\r
people can leave this at the default. If set to "listen", will accept\r
incoming TCP beacons. If you're having issues with your shares not\r
appearing on TiVo, try using the broadcast address of your LAN. For\r
example, if your gateway (router) used address 192.168.1.1, your\r
broadcast address would be 192.168.1.255.  Alternatively, you can\r
specify the exact addresses of your TiVos, e.g. 192.168.1.150\r
192.168.1.151.\r
Example Settings: 192.168.1.255\r
Available In: Server\r
\r
debug\r
\r
Default Setting: False\r
Valid Entries: True/False\r
Required: No\r
Description: Will generate more output for debugging purposes.\r
Example Settings: True/False\r
Available In: Server\r
\r
type\r
\r
Default Setting: None\r
Valid Entries: video, music, photo, or any other valid plugin name.\r
Required: Yes\r
Description: Sets the type of share that this will be. This must be set\r
to something otherwise pyTivo will not start. NOTE plugins names are\r
generally lowercase.\r
Example Settings: video, music, photo\r
Available In: Shares\r
\r
path\r
\r
Default Setting: None\r
Valid Entries: Any operating system path\r
Required: Yes\r
Description: Sets the base path to your media content. While pyTivo will\r
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
force_alpha\r
\r
Default Setting: False\r
Valid Entries: True/False\r
Required: No\r
Description: Only meaningful in shares of type "video". When false, \r
pyTivo will display videos in the order requested by the TiVo, as \r
described at the bottom of the screen. When true, pyTivo will ignore the \r
sort options and revert to its "classic" behavior, using an alphabetical \r
sort always, with folders listed first. Note that the TiVo doesn't \r
request alpha sorts for folders below the top level, so if you want them \r
alpha-sorted, you need this option.\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
Description: Allows for the use of the Optimal Resolution in\r
transcoding. By setting optres = true pyTivo will treat the height and\r
width settings in the conf file as a maximum. If the video to be\r
transcoded has smaller dimensions that are closer to other acceptable\r
TiVo dimensions then pyTivo will use these dimensions. This allows for\r
faster transcoding and small files when the initial video is a lower\r
quality. pyTivo uses the same resolution as the source file on HD Tivos\r
for optimal transcoding efficiency. It is not necessary to to set this\r
option with HD TiVos unless you wish to force pyTivo to change the\r
resolution to an "S2 compatible" resolution.\r
Example Settings: True/False\r
Available In: Tivos, HD_tivos, SD_tivos\r
\r
video_fps\r
\r
Default Setting: 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
Description: Sets the frame rate used by ffmpeg. pyTivo uses 29.97 for\r
S2's, and uses the same frame rate as the source on HD TiVos. The\r
default setting should work fine for most transfers.\r
Example Settings: 29.97, 23.98, 25, 59.94\r
Available In: Tivos, HD_tivos, SD_tivos\r
\r
video_br\r
\r
Default Setting: 4096K for SD TiVo's, 16384K for HD TiVo's\r
Valid Entries: Any valid Bit rate. 1024K = 1Mi\r
Required: No\r
Description: This allows you to choose the default server video bit rate\r
used in transcoding. FFmpeg does not strictly follow this bit rate,\r
there is a certain level of tolerance that is allowed. Also a low\r
quality file will always have a low bit rate. The default is likely fine\r
for most users. Higher values may slow down transcoding and will\r
increase the file size. Increased file sizes take up more room on the\r
TiVo and take longer to transfer over the network. (Higher settings are\r
>recommended for screen sizes above 47" such as: video_br=20Mi, width=1920,\r
height=1080)\r
Example Settings: 4096K, 8Mi, 12Mi, 16Mi, 20Mi\r
Available In: Tivos, HD_tivos, SD_tivos\r
\r
max_video_br\r
\r
Default Setting: 30000k\r
Valid Entries: Any valid Bit rate. 1024K = 1Mi\r
Required: No\r
Description: This allows you to choose the maximum bit rate and is more\r
strict than the video_br setting above. However setting this can cause\r
buffer overflows and can cause issues with ffmpeg. In addition to\r
setting the ffmpeg maxrate option, this setting is used to determine if\r
the video bitrate of the source video file is too high for the TiVo.\r
Otherwise compatible mpeg's with a video bitrate above this setting will\r
be transcoded rather than sent to the TiVo untouched.  Lower this\r
setting below the bitrate of your source file if you wish to force high\r
bitrate sources to be transcoded.  Recommended only for skilled users.\r
Note: there is a report that ffmpeg throws an error with 17Mi but\r
accepts 17408K just fine.\r
Example Settings: 17408k, 30000k\r
Available In: Tivos, HD_tivos, SD_tivos\r
\r
bufsize\r
\r
Default Setting: 1024k for S2, 4096k for S3\r
Valid Entries: Any valid byte size\r
Required: No\r
Description: Allows you to set the buffer size used by ffmpeg.\r
Increasing this setting will allow higher bitrates during transcoding\r
(see video_br setting), especially when transcoding to HD resolutions.\r
But it may result in pixelation or audio sync issues with some sources.\r
1024k is fine for the resolutions used by S2 tivos.  But 2048k or 4096k\r
is preferred for HD tivos.  Leave this setting blank unless you are\r
experiencing audio/video sync issues and wish to test a different value.\r
Example Settings: 1024k, 2048k, 4096k\r
Available In: Tivos, HD_tivos, SD_tivos\r
\r
width\r
\r
Default Setting: 544 for S2, 1920 for S3+\r
Valid Entries: Any valid pixel dimension. Setting will be rounded to\r
nearest acceptable TiVo dimension.\r
Required: No\r
Description: Allows you to choose the output dimension of the transcoded\r
videos. SD units are limited to 720 and below. Likely HD users will want\r
to choose a higher value. Higher values may slow down transcoding and\r
will increase the file size. Increased file sizes take up more room on\r
the TiVo and take longer to transfer over the network.\r
Example Settings: 1920, 1440, 1280, 720, 704, 544, 480, 352.\r
Available In: Tivos, HD_tivos, SD_tivos\r
\r
height\r
\r
Default Setting: 480 for S2, 1080 for S3+\r
Valid Entries: Any valid pixel dimension. Setting will be rounded to\r
nearest acceptable TiVo dimension\r
Required: No\r
Description: Allows you to choose the output dimension of the transcoded\r
videos. SD units are limited to 480 and below. Likely HD users will want\r
to choose a higher value. Higher values may slow down transcoding and\r
will increase the file size. Increased file sizes take up more room on\r
the TiVo and take longer to transfer over the network.\r
Example Settings: 1080, 720, 480\r
Available In: Tivos, HD_tivos, SD_tivos\r
\r
audio_br\r
\r
Default Setting: same bitrate as source or 448k\r
Valid Entries: Any valid bitrate up to 448k\r
Required: No\r
Description: This allows you to choose the default audio bit rate used\r
for transcoding. The default is likely fine for most users. 384k is the\r
minimum recommended for ac3 audio.\r
Example Settings: 192K, 384K, 448K.\r
Available In: Tivos, HD_tivos, SD_tivos\r
\r
max_audio_br\r
\r
Default Setting: 448k\r
Valid Entries: Any valid bitrate\r
Required: No\r
Description: This sets the maximum audio bit rate that can be sent to\r
the TiVo. Files having a higher bit rate will be transcoded to ensure\r
TiVo compatibility.\r
Example Settings: 384K, 448K\r
Available In: Tivos, HD_tivos, SD_tivos\r
\r
audio_fr\r
\r
Default Setting: same frequency as source\r
Valid Entries: 44100, 48000\r
Required: No\r
Description: Sets the audio sampling frequency. Defaults to frequency of\r
the source file for better audio sync if it is 44100 or 48000. Otherwise\r
48000 is used.\r
Example Settings: 44100, 48000\r
Available In: Tivos, HD_tivos, SD_tivos\r
\r
audio_ch\r
\r
Default Setting: same channels as source\r
Valid Entries: any number compatible with ffmpeg and the audio codec selected\r
Required: No\r
Description: Sets the number of audio channels used by ffmpeg. ffmpeg\r
will retain the same number of channels as the source file by default.\r
Change this setting to 2 if you do not want to retain 5.1 audio. A bug\r
in ffmpeg will sometimes move the center audio channel to the left or\r
right speaker. Setting this option to 2, on an as needed basis, or\r
permanently, will correct this at the loss of 5.1 audio. But this should\r
only be necessary on rare occasions where the source file is an mkv or\r
xvid with ac3 5.1 audio bitrate above 448k.\r
Example Settings: 2, 6\r
Available In: Tivos, HD_tivos, SD_tivos\r
\r
audio_lang\r
\r
Recommended Setting: 5.1, DTS, en  (entire string including commas)\r
pyTivo Defaults To: first audio stream\r
Valid Entries: any language tag or audio stream number reported by ffmpeg\r
Required: No\r
Description: Sets the preferred language track used by pyTivo.\r
ffmpeg/pytivo defaults to the first audio stream.  Specifying this\r
parameter, tells pyTivo to use the first audio stream that matches this\r
entry if more than one audio stream exists.  If your video source does\r
not have language tags, you may specify the audio stream number reported\r
by ffmpeg (ie. 0.1, 0.2 ect.). Stream references like 0x80, 0x81, etc.\r
may also be specified.  pyTivo will transcode the file if necessary to\r
obtain the preferred language track.<br><br>\r
You can also assign new language tags to your files by adding Override\r
lines to your metadata txt files.  This will enable pytivo to detect\r
your audio language setting in files that do not contain language tags.\r
The syntax is<br>\r
Override_mapAudio: 0.1 eng<br>\r
Where 0.1 is the audio stream number reported by ffmpeg and eng is the \r
new audio tag to assign to that stream.  You can specify multiple \r
streams with one Override line:<br>\r
Override_mapAudio: 0:1 eng 0:2 "long tag" 0:3 foo<br>\r
Example Settings: eng, ger, spa, en, ge, 0.0, 0.1, 0.2, 0x80, 0x81 etc...\r
Available In: Tivos, HD_tivos, SD_tivos\r
\r
copy_ts\r
\r
Default Setting: True\r
Valid Entries: True/False\r
Required: No\r
Description: Adds the copy timestamps setting (-copyts) to the ffmpeg\r
command.  This setting helps correct audio synchronization problems that\r
commonly occur during transcoding.  You can leave this field blank\r
unless you wish to disable it. pyTivo defaults to True except when\r
pyTivo uses acodec copy, in which case copyts is not needed, and a\r
conflict could also occur if the source file has really corrupt\r
sections.\r
Example Settings: True, False\r
Available In: Tivos, HD_tivos, SD_tivos\r
\r
ffmpeg_pram\r
\r
Default Setting: None\r
Valid Entries: A valid ffmpeg command\r
Required: No\r
Description: This allows you to append additional raw ffmpeg commands to\r
the ffmpeg template. For example, you would enter '-threads 2' here if\r
you have multiple processors and want ffmpeg to use both processors to\r
speed up transcoding.\r
Example Settings: -threads 2\r
Available In: Server, Tivos, HD_tivos, SD_tivos\r
\r
ffmpeg_tmpl\r
\r
Default Setting: %(video_codec)s %(video_fps)s %(video_br)s\r
%(max_video_br)s %(buff_size)s %(aspect_ratio)s\r
%(audio_br)s %(audio_fr)s %(audio_ch)s %(audio_codec)s %(audio_lang)s\r
%(ffmpeg_pram)s %(format)s\r
Valid Entries: A valid ffmpeg command\r
Required: No\r
Description: This is a template used by pyTivo to control the parameters\r
passed to ffmpeg. It should not be necessary to modify this template\r
unless there is a particular parameter you do not wish ffmpeg to use and\r
it cannot be overridden by specifying that parameter in the pyTivo.conf\r
file.\r
Example Settings: See Above and the forum.\r
Available In: Server, Tivos, HD_tivos, SD_tivos\r
\r
aspect169\r
\r
Default Setting: True\r
Valid Entries: True/False\r
Required: No\r
Description: Most TiVos, even S2, can handle 16:9 videos perfectly. Some\r
>S2s are known not to handle 16:9 and will default to false in this\r
setting. If you are experiencing major distortion you can try setting\r
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: None (allow all shares on this TiVo).\r
Valid Entries: The names of any shares in your pyTivo.conf file, in a\r
comma-separated list.\r
Required: No\r
Description: Only the shares listed in this setting will be visible on \r
this TiVo. Will ignore invalid shares. If no valid shares are listed, no \r
shares will be visible on this TiVo. If the "shares" line is not \r
present, all shares are visible.\r
Example Settings: Movies, Kids Stuff\r
Available In: Tivos\r
\r
ffmpeg_wait\r
\r
Default Setting: 0 (no limit)\r
Valid Entries: any integer\r
Required: No\r
Description: Limits the amount of time FFmpeg can run (when used to \r
check file info, not for transcoding), in seconds.\r
Example Settings: 10, 15, 20.\r
Available In: Server\r
\r
tivo_username\r
\r
Default Setting: None\r
Valid Entries: tivo.com username\r
Required: No\r
Description: Your username (email address) at tivo.com. This is required \r
for the "Push" feature. If you don't plan to use Push, you don't need to \r
set this.\r
Example Settings: user@example.com\r
Available In: Server, Tivos\r
\r
tivo_password\r
\r
Default Setting: None\r
Valid Entries: tivo.com password\r
Required: No\r
Description: Your password at tivo.com. This is required for the "Push" \r
feature. If you don't plan to use Push, you don't need to set this.\r
Example Settings: password\r
Available In: Server, Tivos\r
\r
tivo_mind\r
\r
Default Setting: mind.tivo.com:8181\r
Valid Entries: address:port\r
Required: No\r
Description: The TiVo "mind" server and port to use. This is the server \r
that pyTivo connects to in order to make Push requests. For most users \r
in the U.S., the default is the correct value. Australian users will \r
need to use "symind", while users in a beta program need "stagingmind".\r
Example Settings: symind.tivo.com:8181\r
Available In: Server\r
\r
tivo_mak\r
\r
Default Setting: None\r
Valid Entries: Your Media Access Key\r
Required: No\r
Description: Your Media Access Key -- find it on your TiVo under \r
Messages and Settings, Account and System information, Media Access Key. \r
This is required for the "ToGo" feature, and for anything that uses \r
tivodecode (pushing .TiVo files, transcoding HD .TiVo files to SD \r
TiVos). If you don't plan to use these features, you don't need to set \r
this.\r
Example Settings: 012345678\r
Available In: Server, Tivos\r
\r
togo_path\r
\r
Default Setting: None\r
Valid Entries: System path or share name\r
Required: No\r
Description: The path used to save programs downloaded via the ToGo \r
menu. It can be either a direct path, or the name of a share, in which \r
case pyTivo will use the path specified for the share. If you don't plan \r
to use the ToGo feature, you need not set this.\r
Example Settings: My Videos, /home/user/Videos\r
Available In: Server\r
\r
zeroconf\r
\r
Default Setting: Auto\r
Valid Entries: True/False/Auto\r
Required: No\r
Description: Controls whether or not new-style, zeroconf-based beacons \r
are used. The default is to use them, unless there's a "_tivo_" section \r
with "shares" defined. The zeroconf beacons bypass the usual mechanism \r
whereby only the allowed shares are announced to specific TiVos; the \r
contents of the shares will still not appear on unauthorized TiVos, but \r
the names will.\r
Example Settings: True/False/Auto\r
Available In: Server\r
\r
nosettings\r
\r
Default Setting: False\r
Valid Entries: True/False\r
Required: No\r
Description: Disable the "Settings" item in the infopage (i.e. the very \r
thing you're using now). Note that you can't turn this off the way you \r
turned it on, since the settings page will not be available! You'll have \r
to remove it from pyTivo.conf with a text editor.\r
Example Settings: True/False\r
Available In: Server\r