FreeBSD Manual Pages
PODBOAT(1) PODBOAT(1) NAME podboat - a podcast download manager for text terminals SYNOPSIS podboat [-C configfile] [-q queuefile] [-a] [-h] DESCRIPTION Podboat is a podcast manager for text terminals. It is a helper program to Newsboat which queues podcast downloads into a file. These queued downloads can then be download with Podboat. OPTIONS -h, --help Display help -C configfile, --config-file=configfile Use an alternative configuration file -q queuefile, --queue-file=queuefile Use an alternative queue file --lock-file=lockfile Use an alternative lock file -a, --autodownload Start automatic download of all queued files on startup -l loglevel, --log-level=loglevel Generate a logfile with a certain loglevel (valid values: 1 to 6, for user error, critical, error, warning, info, and debug respectively). Filename can be specified using the --log-file option. If not speci- fied, a filename is generated of the form podboat_<date-time>.log -d logfile, --log-file=logfile Use this logfile as output when logging debug messages. Please note that this only works when providing a loglevel. PODCAST SUPPORT A podcast is a media file distributed over the internet using syndication feeds such as RSS, for later playback on portable players or computers. Newsboat supports downloading, saving and streaming podcasts, though an ex- ternal media player is needed for playback. This support differs a bit from other podcast aggregators or "podcatchers" in how it is done. Podcast content is transported in RSS feeds via special tags called "enclo- sures". Newsboat recognizes these enclosures and stores the relevant infor- mation for every podcast item it finds in an RSS feed. Since version 2.0, it also recognizes and handles the Yahoo Media RSS extensions. Remote APIs don't always list those "enclosures", so podcasts might be missing from Newsboat. Such APIs are marked in the relevant section of our docs. If a note is missing but you still don't see enclosures in Newsboat, please file an issue and we'll get to the bottom of it! MANAGING AUDIO FILES WITH PODBOAT What the user can do is to add the podcast download URL to a download queue. Alternatively, Newsboat can be configured to automatically do that. This queue is stored in the queue file next to the cache.db file. The user can then use the download manager podboat to download these files to a directory on the local filesystem. Podboat comes with the Newsboat package, and features a look and feel very close to the one of Newsboat. It also shares the same configuration file. Podcasts that have been downloaded but haven't been played yet remain in the queue but are marked as downloaded. You can remove them by purging them from the queue with the Shift + P key. After you've played a file and close Podboat, it will be removed from the queue. The downloaded file remains on the filesystem unless "delete-played-files" is enabled. A common "use case" is to configure Newsboat to automatically enqueue newly found podcast download URLs. Then, the user reloads the podcast RSS feeds in Newsboat, and after that, uses Podboat to view the current queue, and either selectively download certain files or automatically download them all together by pressing A within Podboat. CONFIGURATION COMMANDS delete-played-files (parameters: [yes/no]; default value: no) If set to yes, Podboat will delete files when their corresponding queue entry is removed (this includes "finished" and "deleted" entries as well). (example: delete-played-files yes) download-path (parameters: <path>; default value: ~/) Specifies the directory where Podboat shall download the files to. Op- tionally, placeholders can be used to place downloads in a directory structure. See the FORMAT STRINGS section of the Newsboat manual for details on available formats. This setting is applied at enqueueing time; changing it won't affect download paths of the podcasts that were already added to the queue. (example: download-path "~/Down- loads/%h/%n") download-filename-format (parameters: <string>; default value: "%?u?%u&%Y-%b-%d-%H%M%S.unknown?") Specifies how Podboat would name the files it downloads (see also down- load-path). See the FORMAT STRINGS section of the Newsboat manual for details on available formats. (example: download-filename-format "%F-%t.%e") max-downloads (parameters: <number>; default value: 1) Specifies the maximum number of parallel downloads when automatic down- load is enabled. (example: max-downloads 3) player (parameters: <player command>; default value: "") Specifies the player that shall be used for playback of downloaded files. (example: player "mp3blaster") podlist-format (parameters: <format>; default value: "%4i [%6dMB/%6tMB] [%5p %%] [%12K] %-20S %u -> %F") This variable defines the format of entries in Podboat's download list. See the FORMAT STRINGS section in the documentation for more informa- tion on format strings. (example: podlist-format "%i %u %-20S %F") FORMAT STRINGS Newsboat contains a powerful format string system to make it possible for the user to configure the format of various aspects of the application, such as the format of entries in the feed list or in the article list. Format strings are similar to those that are found in the printf function in the C programming language. A format sequence begins with the % charac- ter, followed by optional alignment indication: positive numbers indicate that the text that is inserted for the sequence shall be padded on the left to a total width that is specified by the number, while negative number specify padding on the right. Followed by the padding indication comes the actual sequence identifier, which is usually a single letter. %=[width][identifier] centers the sequence, where if w=0 the whole width of the window is used. In addition, Newsboat provides other, more powerful sequences, such as %>[char], which indicates that the text right to the sequence will be aligned right on the screen, and characters between the text on the left and the text on the right will be filled by [char]. Another powerful format is the conditional sequence, %?[char]?[format 1]&[format 2]?: if the text of the sequence identifier [char] contains any non-whitespace characters, then [format 1] will be evaluated and inserted, otherwise [format 2] will be evaluated and inserted. The & and [format 2] are optional, i.e. if the identifier's text is empty, then an empty string will be inserted. The following tables show what sequence identifiers are available for which format: Table 1. Available Identifiers for feedlist-format +------------+-----------------------------+ | | | | Identifier | Meaning | +------------+-----------------------------+ | | | | d | Feed description | +------------+-----------------------------+ | | | | i | Feed index | +------------+-----------------------------+ | | | | l | Feed link | +------------+-----------------------------+ | | | | L | Feed RSS URL | +------------+-----------------------------+ | | | | n | "unread" flag field | +------------+-----------------------------+ | | | | S | download status | +------------+-----------------------------+ | | | | t | Feed title | +------------+-----------------------------+ | | | | T | First tag of a feed in the | | | URLs file | +------------+-----------------------------+ | | | | u | "unread/total" field | +------------+-----------------------------+ | | | | U | "unread" field | +------------+-----------------------------+ | | | | c | "total" field | +------------+-----------------------------+ While a reload-all operation is running, the download status indicates the download status of a feed, which can be "to be downloaded" (indicated by "_"), "currently downloading" (indicated by "."), successfully downloaded (indicated by " ") and "download error" (indicated by "x"). Table 2. Available Identifiers for articlelist-format +------------+-----------------------------+ | | | | Identifier | Meaning | +------------+-----------------------------+ | | | | a | Article author | +------------+-----------------------------+ | | | | D | Publication date. This can | | | be tweaked further with | | | datetime-format | +------------+-----------------------------+ | | | | f | Two characters: 1) "N" if | | | article is unread, "D" if | | | article is deleted, a space | | | otherwise; 2) "!" if arti- | | | cle has flags, a space oth- | | | erwise. | +------------+-----------------------------+ | | | | n | "unread" field | +------------+-----------------------------+ | | | | d | "deleted" field | +------------+-----------------------------+ | | | | F | Article flags | +------------+-----------------------------+ | | | | i | Article index | +------------+-----------------------------+ | | | | t | Article title | +------------+-----------------------------+ | | | | T | If the article list dis- | | | plays articles from differ- | | | ent feeds, then this iden- | | | tifier contains the title | | | of the feed to which the | | | article belongs. | +------------+-----------------------------+ | | | | L | Article length | +------------+-----------------------------+ | | | | e | Article enclosure URL | +------------+-----------------------------+ Table 3. Available Identifiers for selecttag-format +------------+-----------------------------+ | | | | Identifier | Meaning | +------------+-----------------------------+ | | | | i | Line's index in the list | +------------+-----------------------------+ | | | | T | The tag this line corre- | | | sponds to | +------------+-----------------------------+ | | | | f | Number of unread feeds un- | | | der this tag | +------------+-----------------------------+ | | | | n | Number of unread articles | | | in feeds tagged with this | | | tag | +------------+-----------------------------+ | | | | u | Number of feeds tagged with | | | this tag | +------------+-----------------------------+ Table 4. Available Identifiers for notify-format +------------+-----------------------------+ | | | | Identifier | Meaning | +------------+-----------------------------+ | | | | n | Number of unread articles | +------------+-----------------------------+ | | | | f | Number of unread feeds | +------------+-----------------------------+ | | | | d | Number of new unread arti- | | | cles (i.e. that were added | | | through the last reload) | +------------+-----------------------------+ | | | | D | Number of new unread feeds | | | (i.e. that were added | | | through the last reload) | +------------+-----------------------------+ Table 5. Available Identifiers for podlist-format +------------+-----------------------------+ | | | | Identifier | Meaning | +------------+-----------------------------+ | | | | i | Download index | +------------+-----------------------------+ | | | | d | Currently downloaded size | | | in megabytes, displays one | | | digit of precision | +------------+-----------------------------+ | | | | t | Total download size in | | | megabytes, displays one | | | digit of precision | +------------+-----------------------------+ | | | | p | Downloaded precentage, dis- | | | plays one digit of preci- | | | sion | +------------+-----------------------------+ | | | | k | Download speed, displays | | | two digit of precision, al- | | | ways in KB/s (does not in- | | | clude the "KB/s" text) | +------------+-----------------------------+ | | | | K | Download speed, displays | | | two digit of precision, hu- | | | man readable (automatically | | | switches between KB/s, | | | MB/s, and GB/s) | +------------+-----------------------------+ | | | | S | Status of download, dis- | | | plays one of the folowing; | | | "queued", "downloading", | | | "ready", "canceled", | | | "deleted", "missing", | | | "played", "finished" or | | | "failed" | +------------+-----------------------------+ | | | | u | Url of the download | +------------+-----------------------------+ | | | | F | Absolute filename of the | | | download from the root di- | | | rectory (e.g. ~/down- | | | loads/podcast.mp3 -> | | | /home/name/downloads/pod- | | | cast.mp3) | +------------+-----------------------------+ | | | | b | Basename of the download | | | (e.g. /home/name/down- | | | loads/podcast.mp3 -> pod- | | | cast.mp3) | +------------+-----------------------------+ Table 6. Available Identifiers for download-path and download-filename-for- mat +------------+----------------------------------------------+ | | | | Identifier | Meaning | +------------+----------------------------------------------+ | | | | u | Filename part of the down- | | | load URL. May be empty. May | | | include a query string | | | <https://en.wikipedia.org/wiki/Query_string> | +------------+----------------------------------------------+ | | | | n | Name of the podcast feed | +------------+----------------------------------------------+ | | | | N | Name of the podcast feed. Contains the orig- | | | inal feed's name, even when selected through | | | a query feed | +------------+----------------------------------------------+ | | | | h | Name of the podcast feed's hostname | +------------+----------------------------------------------+ | | | | t | Title of the podcast episode | +------------+----------------------------------------------+ | | | | e | Extension of the podcast episode | +------------+----------------------------------------------+ | | | | F | Publication date of the podcast episode for- | | | matted as yyyy-mm-dd | +------------+----------------------------------------------+ | | | | m | Month when podcast episode was published | +------------+----------------------------------------------+ | | | | b | Abbreviated month name when podcast episode | | | was published | +------------+----------------------------------------------+ | | | | d | Day when podcast episode was published | +------------+----------------------------------------------+ | | | | H | Hour when podcast episode was published | +------------+----------------------------------------------+ | | | | M | Minute when podcast episode was published | +------------+----------------------------------------------+ | | | | S | Second when podcast episode was published | +------------+----------------------------------------------+ | | | | y | Year when podcast episode was published for- | | | matted as yy | +------------+----------------------------------------------+ | | | | Y | Year when podcast episode was published for- | | | matted as yyyy | +------------+----------------------------------------------+ Examples: feedlist-format "%4i %n %11u %t" articlelist-format "%4i %f %D %?T?|%-17T| ?%t" notify-format "%d new articles (%n unread articles, %f unread feeds)" podlist-format "%4i [%-5p %%] %-12S %F" FILES By default, Newsboat stores all the files in a traditional Unix fashion, i.e. in a "dotdir" located at ~/.newsboat. However, it also supports a mod- ern way, XDG Base Directory Specification <https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>, which splits the files between the following locations: 1. $XDG_CONFIG_HOME/newsboat/ (XDG_CONFIG_HOME defaults to ~/.config) 2. $XDG_DATA_HOME/newsboat/ (XDG_DATA_HOME defaults to ~/.local/share) If the newsboat directory exists under XDG_CONFIG_HOME, then Newsboat will use XDG directories (creating the data directory if necessary). Otherwise, Newsboat will default to ~/.newsboat. If you're currently using ~/.newsboat/ but wish to migrate to XDG directo- ries, you should move the files as follows: config, urls to $XDG_CONFIG_HOME/newsboat/ cache.db, history.search, history.cmdline, queue to $XDG_DATA_HOME/newsboat/ Newsboat and Podboat also create "lock files". These prevent you from starting two instances of the same program, and thus from corrupting your data. Newsboat and Podboat remove these files when you quit the program, so there is no need to copy them anywhereA a just be aware of them in case you write scripts that work with cache.db or queue. By default, lock files are located as follows: +----------+--------------------+----------------------+ | | | | | | dotdir | XDG | +----------+--------------------+----------------------+ | | | | | Newsboat | ~/.news- | $XDG_DATA_HOME/news- | | | boat/cache.db.lock | boat/cache.db.lock | +----------+--------------------+----------------------+ | | | | | Podboat | ~/.news- | $XDG_DATA_HOME/news- | | | boat/pb-lock.pid | boat/.lock | +----------+--------------------+----------------------+ Newsboat places the lock file next to the cache file, so if you specify cache-file setting or pass --cache-file command-line argument, the path to the lock file will change too. Podboat's lock can be placed elsewhere using --lock-file command-line argument. dotfiles ~/.newsboat/config ~/.newsboat/queue XDG $XDG_CONFIG_HOME/newsboat/config $XDG_DATA_HOME/newsboat/queue Note: if the XDG_CONFIG_HOME environment variable is not set, Podboat behaves as if it was set to ~/.config. Similarly, XDG_DATA_HOME de- faults to ~/.local/share. ENVIRONMENT BROWSER Tells Newsboat what browser to use if there is no browser setting in the config file. If this variable doesn't exist, a default of lynx(1) will be used. CURL_CA_BUNDLE Tells Newsboat to use the specified certificate file to verify the peer. The file may contain multiple certificates. The certificate(s) must be in PEM format. This option is useful if your libcurl is built without useful certifi- cate information, and you can't rebuild the library yourself. EDITOR Tells Newsboat what fallback editor to use when editing the urls file via the edit-urls operation and no VISUAL environment variable is set. If this variable doesn't exist either, a default of vi(1) will be used. NO_PROXY Tells Newsboat to ignore proxy setting for certain sites. This variable contains a comma-separated list of hostnames, domain names, and IP addresses. Domain names match subdomains, i.e. "example.com" also matches "foo.ex- ample.com". Domain names that start with a dot only match subdomains, e.g. ".example.com" matches "bar.example.com" but not "example.com" it- self. IPv6 addresses are written without square brackets, and are matched as strings. Thus "::1" doesn't match "::0:1" even though this is the same address. PAGER Tells Newsboat what pager to use if the pager setting in the config file is explicitly set to an empty string. TMPDIR Tells Newsboat to use the specified directory for storing temporary files. If this variable doesn't exist, a default of /tmp will be used. VISUAL Tells Newsboat what editor to use when editing the urls file via the edit-urls operation. If this variable doesn't exist, the EDITOR envi- ronment variable will be used. XDG_CONFIG_HOME Tells Newsboat which base directory to use for the configuration files. See also the section on files for more information. XDG_DATA_HOME Tells Newsboat which base directory to use for the data files. See also the section on files for more information. SEE ALSO newsboat(1) AUTHOR Alexander Batischev 2026-06-21 PODBOAT(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | PODCAST SUPPORT | MANAGING AUDIO FILES WITH PODBOAT | CONFIGURATION COMMANDS | FORMAT STRINGS | FILES | ENVIRONMENT | SEE ALSO | AUTHOR
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=podboat&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>