1PODBOAT(1) PODBOAT(1)
2
6 podboat - a podcast download manager for text terminals
7
9 podboat [-C configfile] [-q queuefile] [-a] [-h]
10
12 Podboat is a podcast manager for text terminals. It is a helper program
13 to Newsboat which queues podcast downloads into a file. These queued
14 downloads can then be download with Podboat.
15
17 -h, --help
18 Display help
19 -C configfile, --config-file=configfile
21 Use an alternative configuration file
22 -q queuefile, --queue-file=queuefile
24 Use an alternative queue file
25 -a, --autodownload
27 Start automatic download of all queued files on startup
28 -l loglevel, --log-level=loglevel
30 Generate a logfile with a certain loglevel. Valid loglevels are 1
31 to 6. An actual logfile will only be written when you provide a
32 logfile name.
33 -d logfile, --log-file=logfile
35 Use this logfile as output when logging debug messages. Please note
36 that this only works when providing a loglevel.
37
39 A podcast is a media file distributed over the internet using
40 syndication feeds such as RSS, for later playback on portable players
41 or computers. Newsboat supports downloading, saving and streaming
42 podcasts, though an external media player is needed for playback. This
43 support differs a bit from other podcast aggregators or "podcatchers"
44 in how it is done.
45 Podcast content is transported in RSS feeds via special tags called
47 "enclosures". Newsboat recognizes these enclosures and stores the
48 relevant information for every podcast item it finds in an RSS feed.
49 Since version 2.0, it also recognizes and handles the Yahoo Media RSS
50 extensions.
51 Remote APIs don’t always list those "enclosures", so podcasts might be
53 missing from Newsboat. Such APIs are marked in the relevant section of
54 our docs. If a note is missing but you still don’t see enclosures in
55 Newsboat, please file an issue and we’ll get to the bottom of it!
56
58 What the user can do is to add the podcast download URL to a download
59 queue. Alternatively, Newsboat can be configured to automatically do
60 that. This queue is stored in the queue file next to the cache.db file.
61 The user can then use the download manager podboat to download these
63 files to a directory on the local filesystem. Podboat comes with the
64 Newsboat package, and features a look and feel very close to the one of
65 Newsboat. It also shares the same configuration file.
66 Podcasts that have been downloaded but haven’t been played yet remain
68 in the queue but are marked as downloaded. You can remove them by
69 purging them from the queue with the Shift + P key. After you’ve played
70 a file and close Podboat, it will be removed from the queue. The
71 downloaded file remains on the filesystem unless "delete-played-files"
72 is enabled.
73 A common "use case" is to configure Newsboat to automatically enqueue
75 newly found podcast download URLs. Then, the user reloads the podcast
76 RSS feeds in Newsboat, and after that, uses Podboat to view the current
77 queue, and either selectively download certain files or automatically
78 download them all together by pressing A within Podboat.
79
81 delete-played-files (parameters: [yes/no]; default value: no)
82 If set to yes, Podboat will delete files when their corresponding
83 queue entry is removed (this includes "finished" and "deleted"
84 entries as well). (example: delete-played-files yes)
85 download-path (parameters: <path>; default value: ~/)
87 Specifies the directory where Podboat shall download the files to.
88 Optionally, placeholders can be used to place downloads in a
89 directory structure. See "Format Strings" section of Newsboat
90 manual for details on available formats. This setting is applied at
91 enqueueing time; changing it won’t affect download paths of the
92 podcasts that were already added to the queue. (example:
93 download-path "~/Downloads/%h/%n")
94 download-filename-format (parameters: <string>; default value:
96 "%?u?%u&%Y-%b-%d-%H%M%S.unknown?")
97 Specifies how Podboat would name the files it downloads (see also
98 download-path). See "Format Strings" section of Newsboat manual for
99 details on available formats. (example: download-filename-format
100 "%F-%t.%e")
101 max-downloads (parameters: <number>; default value: 1)
103 Specifies the maximum number of parallel downloads when automatic
104 download is enabled. (example: max-downloads 3)
105 player (parameters: <player command>; default value: "")
107 Specifies the player that shall be used for playback of downloaded
108 files. (example: player "mp3blaster")
109 podlist-format (parameters: <format>; default value: "%4i [%6dMB/%6tMB]
111 [%5p %%] [%12K] %-20S %u → %F")
112 This variable defines the format of entries in Podboat’s download
113 list. See the respective section in the documentation for more
114 information on format strings. (example: podlist-format "%i %u
115 %-20S %F")
116
118 By default, Newsboat stores all the files in a traditional Unix
119 fashion, i.e. in a "dotdir" located at ~/.newsboat. However, it also
120 supports a modern way, XDG Base Directory Specification
121 <https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>,
122 which splits the files between the following locations:
123 1. $XDG_CONFIG_HOME/newsboat/ (XDG_CONFIG_HOME defaults to ~/.config)
125 2. $XDG_DATA_HOME/newsboat/ (XDG_DATA_HOME defaults to ~/.local/share)
127 If the newsboat directory exists under XDG_CONFIG_HOME, then Newsboat
129 will use XDG directories (creating the data directory if necessary).
130 Otherwise, Newsboat will default to ~/.newsboat.
131 If you’re currently using ~/.newsboat/ but wish to migrate to XDG
133 directories, you should move the files as follows:
134 config, urls
136 to $XDG_CONFIG_HOME/newsboat/
137 cache.db, history.search, history.cmdline, queue
139 to $XDG_DATA_HOME/newsboat/
140 Newsboat and Podboat also create "lock files". These prevent you from
142 starting two instances of the same program, and thus from corrupting
143 your data. Newsboat and Podboat remove these files when you quit the
144 program, so there is no need to copy them anywhere — just be aware of
145 them in case you write scripts that work with cache.db or queue. By
146 default, lock files are located as follows:
147 ┌─────────┬───────────────────────────┬───────────────────────────────────────┐
149 │ │ │ │
150 │ │ dotdir │ XDG │
151 ├─────────┼───────────────────────────┼───────────────────────────────────────┤
152 │ │ │ │
153 │Newsboat │ ~/.newsboat/cache.db.lock │ $XDG_DATA_HOME/newsboat/cache.db.lock │
154 ├─────────┼───────────────────────────┼───────────────────────────────────────┤
155 │ │ │ │
156 │Podboat │ ~/.newsboat/pb-lock.pid │ $XDG_DATA_HOME/newsboat/.lock │
157 └─────────┴───────────────────────────┴───────────────────────────────────────┘
158 Newsboat places the lock file next to the cache file, so if you specify
160 cache-file setting or pass —cache-file command-line argument, the path
161 to the lock file will change too. Podboat, on the other hand, always
162 places its lock file as shown above.
163 dotfiles
165 ~/.newsboat/config
166 ~/.newsboat/queue
168 XDG
170 $XDG_CONFIG_HOME/newsboat/config
171 $XDG_DATA_HOME/newsboat/queue
173 Note: if the XDG_CONFIG_HOME environment variable is not set,
175 Podboat behaves as if it was set to ~/.config. Similarly,
176 XDG_DATA_HOME defaults to ~/.local/share.
177
179 BROWSER
180 Tells Newsboat what browser to use if there is no browser setting
181 in the config file. If this variable doesn’t exist, a default of
182 lynx(1) will be used.
183 CURL_CA_BUNDLE
185 Tells Newsboat to use the specified certificate file to verify the
186 peer. The file may contain multiple certificates. The
187 certificate(s) must be in PEM format.
188 This option is useful if your libcurl is built without useful
190 certificate information, and you can’t rebuild the library
191 yourself.
192 EDITOR
194 Tells Newsboat what fallback editor to use when editing the urls
195 file via the edit-urls operation and no VISUAL environment variable
196 is set. If this variable doesn’t exist either, a default of vi(1)
197 will be used.
198 NO_PROXY
200 Tells Newsboat to ignore proxy setting for certain sites.
201 This variable contains a comma-separated list of hostnames, domain
203 names, and IP addresses.
204 Domain names match subdomains, i.e. "example.com" also matches
206 "foo.example.com". Domain names that start with a dot only match
207 subdomains, e.g. ".example.com" matches "bar.example.com" but not
208 "example.com" itself.
209 IPv6 addresses are written without square brackets, and are matched
211 as strings. Thus "::1" doesn’t match "::0:1" even though this is
212 the same address.
213 PAGER
215 Tells Newsboat what pager to use if the pager setting in the config
216 file is explicitly set to an empty string.
217 TMPDIR
219 Tells Newsboat to use the specified directory for storing temporary
220 files. If this variable doesn’t exist, a default of /tmp will be
221 used.
222 VISUAL
224 Tells Newsboat what editor to use when editing the urls file via
225 the edit-urls operation. If this variable doesn’t exist, the EDITOR
226 environment variable will be used.
227 XDG_CONFIG_HOME
229 Tells Newsboat which base directory to use for the configuration
230 files. See also the section on files for more information.
231 XDG_DATA_HOME
233 Tells Newsboat which base directory to use for the data files. See
234 also the section on files for more information.
235
237 newsboat(1)
238
240 Alexander Batischev
241 2023-09-25 PODBOAT(1)