improve documentation in example configuration file (#386)

Improve sentence structure, general grammar, consistency and correct some incorrect setting names. Also wrap lines at roughly 82 columns for easier viewing.
2024-05-14 04:14:58 +12:00
parent 97d47d7073
commit 0977b56385
1 changed files with 119 additions and 102 deletions
--- a/configuration.example.ini
+++ b/configuration.example.ini
@@ -1,13 +1,13 @@
 # ========================================================
-#  botamusique Example Configuration File
+#  botamusique example configuration file
 #  Version 6
 # ========================================================
-#  Rename this file into configuration.ini after editing.
-#  Uncomment lines you needed, and carefully follow the
-#  instructions.
+#  Rename this file to configuration.ini after editing.
+#  Uncomment lines you'd like to change, and carefully
+#  follow the instructions.
 # ========================================================

-# [server] section tells the bot how to connect to your murmur server.
+# The [server] section tells the bot how to connect to your Murmur server.
 # This section will be overridden by command line arguments.
 [server]
 host = 127.0.0.1
@@ -17,203 +17,220 @@ port = 64738
 #tokens = token1,token2
 #certificate =

-# [bot] section stores some basic settings of the behavior of the bot.
+# The [bot] section stores some basic settings for the bot.
 [bot]
-# 'username' is the user name of the bot.
-# 'comment' is the comment displayed by the bot.
-# 'avatar' is the path to the avatar image shown on the bot (PNG recommended, 128 KB max).
+# 'username': The bot's username.
+# 'comment': Comment displayed on the bot's profile.
+# 'avatar': Path to an image used for the bot's avatar (PNG recommended, 128 KB max).
 #username = botamusique
 #comment = "Hi, I'm here to play radio, local music or youtube/soundcloud music. Have fun!"
 #avatar =

-# 'language': Available languages can be found inside lang/ folder.
+# 'language': Language to use; available languages can be found inside
+#    the lang/ folder.
 #language=en_US

 # 'music_folder': Folder that stores your local songs.
 #music_folder = music_folder/

-# 'database_path': The path of the database. The database will store things like your volume
-#    set by command !volume, your playback mode and your playlist, banned URLs, etc.
+# 'database_path': The path of the database, which stores things like your
+#    volume set by the !volume command, your playback mode and your playlist,
+#    banned URLs, etc.
 #    This option will be overridden by command line arguments.
-# 'music_database_path': The path of database that stores the music library. Can be disabled by
-#    setting 'save_music_library=False'
+# 'music_database_path': The path of the database that stores the music library.
+#    Can be disabled by setting 'save_music_library = False'
 #database_path=settings.db
 #music_database_path=music.db

-# 'admin': Users allowed to kill the bot, or ban URLs. Separated by ';'
+# 'admin': List of users allowed to kill the bot, or ban URLs.
+#    Separated by ';'.
 #admin = User1;User2;

-# 'stereo': After 1.4.0, mumble starts to support stereo stream. Enable this option for stereo
-#    stream transmission. Otherwise the bot will down mix stereo sound into mono.
+# 'stereo': Enable stereo stream transmission, supported since Mumble 1.4.0.
+#    If this is not enabled, the bot will downgrade stereo sound into mono.
 #stereo = True

-# 'volume' is default volume from 0 to 1.
-# This option will be overridden by value in the database.
+# 'volume': The default volume, a number from 0 to 1.
+#    This option will be overridden by the value set in the database.
 #volume = 0.1

-# 'bandwidth' is the number of bits per second used by the bot when streaming audio. Enabling this
-#    option will allow you to set it higher than the default value. If the value exceeds the servers
-#    bitrate, the bitrate used by the bot will match the servers.
+# 'bandwidth': The number of bits per second used by the bot when streaming audio.
+#    Enabling this option will allow you to set it higher than the default value.
+#    If the given value exceeds the server's bitrate, the bitrate used by the bot
+#    will match the server's.
 #bandwidth = 200000

-# 'playback_mode' defined the playback mode of the bot.
-#    it should be one of "one-shot" (remove item once played), "repeat" (looping through the playlist),
-#    or "random" (randomize the playlist), "autoplay" (randomly grab something from the music library).
-#    This option will be overridden by value in the database.
-# 'autoplay_length': how many songs the autoplay mode fills the playlist
-# 'clear_when_stop_in_oneshot': clear the playlist when stopping the bot in one-shot mode.
+# 'playback_mode': The playback mode of the bot. It should be one of the below:
+#     one-shot: remove item once it has finished playing
+#     repeat: repeat the playlist
+#     random: randomize the order of the playlist
+#     autoplay: randomly pick a track from the music library
+#    This option will be overridden by the value set in the database.
+# 'autoplay_length': How many songs to fill the playlist with in autoplay mode.
+# 'clear_when_stop_in_oneshot': Whether to clear the playlist when stopping the
+#    bot in one-shot mode.
 #playback_mode = one-shot
 #autoplay_length = 5
 #clear_when_stop_in_oneshot = False

-# target version, stable or testing (testing needs to be installed with git)
-# stable will use simple bash with curl command to get releases, testing will follow github master branch with git commands
+# 'target_version': version to fetch when updating:
+#    stable: use the curl command to get stable releases
+#    testing: follow git master branch using the git command
 #target_version = stable

-# 'tmp_folder': Folder that stores the downloaded music.
-# 'tmp_folder_max_size': in MB, 0 for no cache, -1 for unlimited size
-# 'ignored_folders', 'ignored_files': files and folders that would be ignored during scanning.
+# 'tmp_folder': Folder that music will be downloaded into.
+# 'tmp_folder_max_size': Maximum size of tmp_folder in MB, or 0 to not cache
+#    at all, or -1 for unlimited size
+# 'ignored_files', 'ignored_folders': Files and folders to ignore during scanning.
 #tmp_folder = /tmp/
 #tmp_folder_max_size = 10
 #ignored_folders = tmp
 #ignored_files = Thumbs.db

-# 'download_attempts': how many times the bot will try to download an item
+# 'download_attempts': How many times to attempt a download.
 #download_attempts = 2

-# 'auto_check_update': check for updates every time the bot starts, post the changelog after an update was applied
+# 'auto_check_update': Whether to check for updates every time the bot starts,
+#    and post the changelog after an update was applied.
 #auto_check_update = True
 #pip3_path = venv/bin/pip

-# 'logfile': write logs into this file.
-# 'redirect_strerr': capture outputs from stderr and write into the `logfile`,
-#                    useful for capture the exception message when the bot crash.
+# 'logfile': File to write log messages to.
+# 'redirect_stderr': Whether to capture outputs from standard error and write
+#    it into the log file. Useful for capturing an exception message when the
+#    bot crashes.
 #logfile =
-#redirect_strerr = False
+#redirect_stderr = False

 #announce_current_music = True
 #allow_other_channel_message = False
 #allow_private_message = True

-# 'delete_allowed': Allow users to delete a file from the library (hard disk).
-#    Works both for command and web interface. After enabling this option, only
-#    admins are allowed to delete files.
+# 'delete_allowed': Whether to allow admins to delete a file from the library
+#    stored on disk. Works for both command and web interfaces.
 #delete_allowed = True

-# 'save_music_library': If this is set True, the bot will save the metadata of music into the database.
+# 'save_music_library': Whether to save music metadata to the database.
 #save_music_library = True

-# 'refresh_cache_on_startup': If this is set true, the bot will refresh its music directory cache when starting up.
-#     But it won't reload metadata from each files. If set to False, it will used the cache last time.
+# 'refresh_cache_on_startup': Whether to refresh the music directory's cache when
+#    starting up. Metadata from each file will not be refreshed. If this is False,
+#    the cache from last time will be used.
 #refresh_cache_on_startup = True

-# 'save_playlist': If save_playlist is set True, the bot will save current playlist before quitting
-#    and reload it the next time it start. It requires save_music_library to be True to function.
+# 'save_playlist': Whether to save the current playlist before quitting, so that
+#    it may be reloaded next time. To use this, save_music_library must be True.
 #save_playlist = True

-# 'max_volume': Maximum volume able to be set by users. 0.0 - 1.0
+# 'max_volume': Maximum volume users are allowed to set.
+#    Number between 0.0 - 1.0.
 #max_volume = 0.8

-# 'max_track_playlist': Maximum track played when a playlist is added.
+# 'max_track_playlist': The maximum amount of tracks allowed in a playlist.
 #max_track_playlist = 20

-# 'max_track_duration': Maximum music duration (minutes)
+# 'max_track_duration': Maximum track duration in minutes.
 #max_track_duration = 60

-# 'ducking': If ducking is enabled, the bot will automatically attenuate its
-#     volume when someone is talking.
+# 'ducking': Whether to lower music volume when someone is talking.
 #ducking = False
 #ducking_volume = 0.05
 #ducking_threshold = 3000

-# 'when_nobody_in_channel': Specify what the bot should do if nobody is in the channel.
-#    Possible value of this options are:
-#     - "pause",
-#     - "pause_resume" (pause and resume once somebody re-enters the channel)
-#     - "stop" (also clears playlist)
-#     - leave empty (do nothing)
+# 'when_nobody_in_channel': Behaviour of the bot when nobody is in the channel.
+#    Has to be one of:
+#     pause: pause the current track
+#     pause_resume: pause the current track and resume it once someone joins
+#     stop: stop the bot, clearing its playlist
+#    Or you can leave it empty to take no action.
 #when_nobody_in_channel =

-# 'when_nobody_in_channel_ignore': Specify the list of users that should be ignored, from the list of active users.
-#   This is typically used when other bots are present in the channel.
+# 'when_nobody_in_channel_ignore': List of users that should be ignored.
+#    This is typically used when other bots are present in the channel.
 #when_nobody_in_channel_ignore =

-# 'youtube_query_cookie': Sometimes youtube will block the request of our bot and
-#   request the bot to complete a captcha to verify the request is not made by a
-#   bot.
-#   This problem can be resolved if the bot bears a valid cookie.
-#   If the bot complains "unable to query youtube", you may try to add your cookie here.
+# 'youtube_query_cookie': Sometimes YouTube will block the bot's request and ask
+#    the bot to complete a captcha to verify the request is made by a human. This
+#    can be solved if the bot has a valid cookie. If the bot complains "unable to
+#    query youtube", you should provide a value here.
 #youtube_query_cookie = {"CONSENT": "paste your CONSENT cookie value here"}

-# [webinterface] stores settings related to the web interface.
+# The [webinterface] section stores settings related to the web interface.
 [webinterface]
-# 'enable': Set 'enabled' to True if you'd like to use the web interface to manage
-#     your playlist, upload files, etc.
-#     The web interface is disabled by default for security and performance reasons.
-# 'access_address': Used when users are requesting the address to access the web interface.
+# 'enabled': Whether to enable the web interface to allow managing your playlist,
+#    uploading tracks, etc.
+#    The web interface is disabled by default for security and performance reasons.
+# 'access_address': URL provided to users when the public URL for the
+#    web interface is requested.
 #enabled = False
 #listening_addr = 127.0.0.1
 #listening_port = 8181
 #is_web_proxified = True
-# This is the public URL
 #access_address = http://127.0.0.1:8181

-# 'web_logfile': write access logs of the web server into this file.
+# 'web_logfile': If this is provided, web server access logs are written to this file.
 #web_logfile =

 # 'auth_method': Method used to authenticate users accessing the web interface.
-#                Options are 'none', 'password' or 'token' (use unique token, see
-#                requests_webinterface_access command)
-# 'max_attempts': Bad access attempts before being banned. Regenerating a token or
-#                 rebooting the bot will reset this attempts tally.
+#    One of 'none', 'password' or 'token'. If this is set to 'token', a unique token
+#    is used for authentication.
+# 'max_attempts': Amount of incorrect login attempts needed before being banned.
+#    Regenerating a token or rebooting the bot will reset this number.
 #auth_method = token
 #max_attempts = 10

-# 'user', 'password': If auth_method set to 'password', you need to set the default
-#                     username and password. You can add more users by '!webadduser'
+# 'user', 'password': If auth_method is set to 'password', you'll need to set
+#    the default username and password, which is set by these two options.
+#    You can add more users using the '!webadduser' command.
 #user = botamusique
 #password = mumble

-# 'flask_secret': To use a token, flask needs a password to encrypt/sign cookies.
-#                 !! YOU NEED TO CHANGE IT IF auth_method IS 'token'!!
-# flask_secret = ChangeThisPassword
+# 'flask_secret': To use a token, Flask needs a password to encrypt/sign cookies.
+#    This is absolutely necessary if auth_method is 'token'!
+#flask_secret = ChangeThisPassword

-# 'upload_enabled': Enable the upload function of the web interface. If disabled,
-#    only admins can upload files.
-# 'maximum_upload_file_size': Unit can be 'B', 'KB', 'MB', 'GB', 'TB'.
+# 'upload_enabled': Whether to enable the upload function of the web interface.
+#    If this is False, only admins can upload files.
+# 'maximum_upload_file_size': Maximum file size allowed for uploads.
+#    Can be specified in B, KB, MB, GB, or TB.
 #upload_enabled = True
 #max_upload_file_size = 30MB

-# [debug] stores some debug settings.
+# The [debug] section contains settings to enable debugging messaages.
 [debug]
-# Set ffmpeg to True if you want to display DEBUG level log of ffmpeg.
-#ffmpeg = False 
-# Set to True if you need to debug mumble connection (pymumble lib)
-#mumble_connection = False 
-# Set to True if you need debug log from youtube-dl
-#youtube_dl = False 
+# 'ffmpeg': Whether to display debug messages from ffmpeg.
+# 'mumble_connection': Whether to display debug messages for the
+#    connection to the Mumble server (from the pymumble library).
+# 'youtube_dl': Whether to display debug messages from youtube-dl.
+#ffmpeg = False
+#mumble_connection = False
+#youtube_dl = False

-# [radio] is a list of default radio stations.
+# The [radio] section contains a list of default radio stations.
 [radio]
 # List of radio stations you want to have by default, one entry per line.
 #jazz = http://jazz-wr04.ice.infomaniak.ch/jazz-wr04-128.mp3 "Jazz Yeah !"

-# [youtube_dl] are options to customize youtube-dl (optional)
+# The optional [youtube_dl] section contains options to customize youtube-dl
 [youtube_dl]
-# source_address , use '::' to force ipv6, "0.0.0.0" to force ipv4, or put the ip addresse you want to use.
+# 'source_address': Set to '::' to force ipv6, "0.0.0.0" to force ipv4,
+#    or else put the IP address you want to use here.
+# 'cookie_file': Path of the cookie file to use, useful if you are being rate limited:
+#    <https://github.com/ytdl-org/youtube-dl#http-error-429-too-many-requests-or-402-payment-required>
+# 'user_agent': Set the User-Agent header when making requests to youtube.com.
 # source_address = '::'
-# cookie_file , path of the cookie file (usefull if you reach youtube limits https://github.com/ytdl-org/youtube-dl#http-error-429-too-many-requests-or-402-payment-required)
-# cookie_file = '/tmp/cooke_ydl'
-# user-agent allow the user to force the user-agent of youtube-dl
+# cookie_file = /tmp/youtube-dl-cookie
 # user-agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:87.0) Gecko/20100101 Firefox/87.0"

-# [commands] are settings related to user command sent via mumble message.
+# The [commands] section contains settings related to user commands sent via
+# Mumble text messages.
 [commands]
-# 'command_symbol' is a list of characters the bot recognizes as command prefix.
-#command_symbol = !:！
-# 'split_username_at_space': This option split username, in case you use such kind of mumo plugins https://wiki.mumble.info/wiki/Mumo#Set_Status
+# 'command_symbol': List of characters recognized as a command prefix.
+# 'split_username_at_space': Whether usernames should be split by a space,
+#    in case you use these kinds of Mumo plugins:
+#    <https://wiki.mumble.info/wiki/Mumo#Set_Status>
 #split_username_at_space = False
-
+#command_symbol = !:！

 # You may also customize commands recognized by the bot. For a full list of commands,
 #    see configuration.default.ini. Copy options you want to edit into this file.