-
Notifications
You must be signed in to change notification settings - Fork 1
User Guide
The following is a very basic user guide on how to use Podbit.
- Have podbit installed (duh)
- Have newsboat installed
- Have newsboat configured with one or more podcast RSS feeds
In newsboat, navigate to the RSS feed of your podcast. Once newsboat has downloaded and parsed the feed, it should display each episode as a separate entry in the RSS entries list. Open one of these entries by pressing enter. Once in the feed, the episode notes/description will be displayed. Once happy that you want to listen to this specific episode, press "e" on your keyboard. At the bottom of your screen, newsboat will tell you that it has enqueued this episode. What this means is that the download URL it extracted from the RSS feed has been placed in the queue file. You do not need to edit this file at all, but knowing it is there can be useful.
At your terminal, open podbit. Once podbit has loaded (could take some time on initial load, often not though), you will see a library of all the podcasts you will or ever have listened to, extracted from the queue file mentioned earlier. Each episode can either be "pending", "ready", "played" or "finished". Pending podcasts will need to be downloaded before they can be played. Ready podcasts are downloaded onto the disk cache and can be played at a moment's notice. Played podcasts have been listened to at least once. Finished podcasts have been listened to all the way through and can be deleted on next cache cleanout.
In your library, you will see the episode you juse enqueued. The library view will usually show the podcast name to your left and the episode name/URL to the right, but - as you haven't configured any podcasts yet - only the URL will be shown. To learn about configuring podcast names, see here. For now, we will ignore this.
Moving your selection in podbit is done using vi-like keys. Press "j" to move your selection down, "k" to move up, "l" to move to the right and "h" to the left. These keys are in a row intentionally and are on your home row on the keyboard, meaning that your fingers never need to move far from when typing commands or issuing other keybinds. To select your podcast to download, press "h" and then press the spacebar. A message will display telling you that your download has started. Now, press "3" on your keyboard. The number keys are bound to showing different displays. These displays are as follows:
- Player Shows player status, a statusbar of how far you have played, as well as episode and podcast names in a nice pretty layout (this is mostly for eyecandy and a nice UI)
- Queue Shows episodes queued to play. Episodes marked with an exclamation mark "!!" will be downloaded before playing. The currently playing episode is marked with an arrow ">>"
- Downloads Shows episodes currently downloading. Podbit downloads all episodes (up to GOMAXPROCS, that is) in parallel for maximum speed
- Library An organised menu of all podcast episodes by their podcast name. Downloads and play enqueues can be issued from here with the space bar and enter key - enter enqueueing to play, space to download
Once you have pressed "3", you will see a list of currently ongoing downloads (currently only the one), their percent completed and status. From here, you can cancel the downloads with "d" or enqueue it to play once completed with the enter key.
Once the download has completed, you can press enter to enqueue the downloaded file to play. You could also press enter while the download was ongoing and it would play automatically once completed. If you had other media queued at the time, it would continued downloading and play once reached in the queue.
Navicate to the player by pressing "1". You can move forward a second by pressing "]" and back with "[". You can rought seek by one minute with "}" and "{". The player is paused with "p" from anywhere or space from the player screen. "s" stops the current media file and moves on the the next one.
Media is played using mpv in the background. This means that all your existing mpv configs will be loaded into podbit on mpv startup (such as audio config, filters and integrations with MPRIS, etc). For this to work, mpv does need to be installed and in your $PATH.
Podbit is designed to be allowed to run in the background as you use newsboat. As such, it has support for hot-reloading the queue file and merging the contents it already loaded. You can do this manually by pressing "r" from anywhere in podbit. You can also wait for one minute, at which point podbit will automatically reload the queue file.
I implemented this to fix the behaviour of podboat, which would not reload the queue file while running, leading to me needing to close the program and re-open, closing any ongoing downloads and/or playing media. The most annoying part was that podboat would occasionally truncate the file to zero bytes (clearing all the contents in the process) on reload, removing all my progress. I was not going to allow this behaviour into podbit.
Unlike vim, podbit is simple to exit. Just press "q".
Note that podbit will refuse to exit while podcast downloads are ongoing. If you really need to exit, you can cancel all downloads by pressing "d" on each download in the download menu, or by running kill -9 $(pidof podbit). Note that the latter will corrupt the ongoing download files and will likely mess up whatever terminal you were using because of ncurses.
- "Unknown terminal" - Make sure your terminal installed a terminfo registry. xterm, konsole, gnome terminal, st and most others do this for you
- "Could not detect queue file" - You need to enqueue media at least once before launching podbit, as it loads the episodes initially on startup
- "Failed to init sound system" - You need mpv installed to play media, which is checked at startup. Install mpv from your package manager and try again