Still need to skip "_tivo_4K" sections when building list of found TiVos.

[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, FK_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 transcoding \r
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
Mode: checkbox\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
Mode: select\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
Mode: checkbox\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
force_ffmpeg\r
\r
Mode: checkbox\r
Default Setting: False\r
Valid Entries: True/False\r
Required: No\r
Description: Only meaningful in shares of type "music". When false, \r
pyTivo will pass through TiVo-compatible MP3 files as-is (unless you \r
seek within them). When true, even these files will be processed by \r
FFmpeg, in order to strip out album artwork that the TiVo would \r
otherwise try to play as sound, producing a squeal. This is done with \r
the "copy" codec, so it's low-overhead.\r
Example Settings: True/False\r
Available In: Shares\r
\r
allow_recurse\r
\r
Mode: select\r
Options: Auto/On/Off\r
Default Setting: Auto\r
Valid Entries: On/Off/Auto\r
Required: No\r
Description: Only meaningful in shares of type "video". The TiVo uses \r
the "Recurse" option in a query to provide a flattened, ungrouped \r
listing. Recent versions of the TiVo software sometimes forget the \r
grouping flag, and unexpectedly request an ungrouped list. So, the \r
default now is to ignore the "Recurse" flag on those platforms. This \r
option lets you enable it anyway ("Yes"), or force it to be ignored even \r
on TiVos that aren't recognized as having the bug ("No").\r
Example Settings: On/Off/Auto\r
Available In: Shares\r
\r
optres\r
\r
Mode: checkbox\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, FK_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, FK_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, FK_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, FK_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, FK_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, FK_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, FK_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, FK_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_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 (transcoding HD .TiVo files to SD TiVos). If you don't plan \r
to use these features, you don't need to set 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
Mode: select\r
Options: Auto/On/Off\r
Default Setting: Auto\r
Valid Entries: On/Off/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: On/Off/Auto\r
Available In: Server\r
\r
ts\r
\r
Mode: select\r
Options: Auto/On/Off\r
Default Setting: Auto\r
Valid Entries: On/Off/Auto\r
Required: No\r
Description: Should pyTivo use transport stream mode with supported \r
TiVos? On = Send only transport streams; Off = Send only program \r
streams; Auto = Send as-is if compatible, or as transport stream if the \r
source is likely (based on the extension) to be h.264, or program stream \r
otherwise. .TiVo files are sent as-is regardless of this setting (unless \r
the destination TiVo can't handle transport streams.)\r
Example Settings: On/Off/Auto\r
Available In: Server\r
\r
nosettings\r
\r
Mode: checkbox\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