From 8f911cc880fe5ffa389400c552dc54ef428c3d41 Mon Sep 17 00:00:00 2001 From: gilcu3 <828241+gilcu3@users.noreply.github.com> Date: Mon, 20 May 2024 16:29:08 +0200 Subject: [PATCH] improve README and default config --- README.md | 183 +++++++++++++++++++++++++++------------------------- config.toml | 34 ++++++++++ 2 files changed, 129 insertions(+), 88 deletions(-) diff --git a/README.md b/README.md index db42fe8..845abe9 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,37 @@ # Hullcaster -Hullcaster is a terminal-based podcast manager, built in Rust. It provides a terminal UI (i.e., an ncurses-like interface) to allow users to subscribe to podcast feeds, and sync feeds to check for new episodes. Episodes may be downloaded locally, played with an external media player, and marked as played/unplayed. Keybindings and other options are configurable via a config file. +Hullcaster is a terminal-based podcast manager, built in Rust. It provides a +terminal UI (i.e., an ncurses-like interface) to allow users to subscribe to +podcast feeds, and sync feeds to check for new episodes. Episodes may be +downloaded locally, played with an external media player, and marked as +played/unplayed. Key bindings and other options are configurable via a config +file. ## Note -This is a fork of [shellcaster](https://github.com/jeff-hughes/shellcaster), which is no longer maintained. Currently, I am planning to implement the features states in `TODO.md`, while learning `rust` at the same time. +This is a fork of [shellcaster](https://github.com/jeff-hughes/shellcaster), +which is no longer maintained. Currently, I am planning to implement the +features stated below, while learning `rust` at the same time. + +### Planned changes + +- [x] Option to avoid marking as read when playing +- [x] Syncing with gpodder episode actions api (rudimentary, tested with + [opodsync](https://github.com/kd2org/opodsync)) +- [ ] Queue +- [ ] Internal Player +- [x] Show key bindings in a bar on the bottom +- [ ] Fix performance of mark-all as read +- [ ] Fix bug deleting file +- [ ] Show the podcast description only when a podcast is selected +- [ ] Fix syncing podcasts, sometimes gets stuck (it seems timeout not working) +- [ ] Support the syncing subscriptions with gpodder ## Installing hullcaster -### On Linux distributions and MacOS +### On Linux distributions -Currently the only option is to build from source. +Currently, the only option is to build from source. First, ensure you have installed the necessary dependencies: @@ -21,9 +42,14 @@ First, ensure you have installed the necessary dependencies: **Notes:** -* The names of these dependencies may be slightly different for your system. For `libsqlite3-dev`, you are looking for the development headers for SQLite, which may be separate from the runtime package (e.g., with a `-dev` suffix). -* If you enable the "native_tls" feature of hullcaster (disabled by default), you will also need `libssl-dev`, the development headers for OpenSSL (not needed on MacOS). -* If you enable the "sqlite-bundled" feature of hullcaster (disabled by default), `pkg-config` and `libsqlite3-dev` are not necessary. +* The names of these dependencies may be slightly different for your system. For + `libsqlite3-dev`, you are looking for the development headers for SQLite, + which may be separate from the runtime package (e.g., with a `-dev` suffix). +* If you enable the "native_tls" feature of hullcaster (disabled by default), + you will also need `libssl-dev`, the development headers for OpenSSL (not + needed on MacOS). +* If you enable the "sqlite-bundled" feature of hullcaster (disabled by + default), `pkg-config` and `libsqlite3-dev` are not necessary. Next, you can clone the Github repo and compile it yourself: @@ -32,17 +58,12 @@ git clone https://github.com/gilcu3/hullcaster.git cd hullcaster cargo build --release # add or remove any features with --features -# for MacOS or Linux -sudo cp target/release/hullcaster /usr/local/bin/ - -# or for Linux, no root permissions +# no root permissions cp target/release/hullcaster ~/.local/bin ``` See below for the list of available features when compiling. - - ## Running hullcaster Easy-peasy! In your terminal, run: @@ -51,7 +72,8 @@ Easy-peasy! In your terminal, run: hullcaster ``` -Note that if you installed hullcaster to a different location, ensure that this location has been added to your `$PATH`: +Note that if you installed hullcaster to a different location, ensure that this +location has been added to your `$PATH`: ```bash export PATH="/path/to/add:$PATH" @@ -59,13 +81,17 @@ export PATH="/path/to/add:$PATH" ## Importing/exporting podcasts -Hullcaster supports importing OPML files from other podcast managers. If you can export to an OPML file from another podcast manager, you can import this file with: +Hullcaster supports importing OPML files from other podcast managers. If you can +export to an OPML file from another podcast manager, you can import this file +with: ```bash hullcaster import -f /path/to/OPML/file.opml ``` -If the `-r` flag is added to this command, it will overwrite any existing podcasts that are currently stored in hullcaster. You can also pipe in data to `hullcaster import` from stdin by not specifying the `-f `. +If the `-r` flag is added to this command, it will overwrite any existing +podcasts that are currently stored in hullcaster. You can also pipe in data to +`hullcaster import` from stdin by not specifying the `-f `. You can export an OPML file from hullcaster with the following command: @@ -73,7 +99,8 @@ You can export an OPML file from hullcaster with the following command: hullcaster export -f /path/to/output/file.opml ``` -You can also export to stdout by not specifying the `-f `; for example, this command is equivalent: +You can also export to stdout by not specifying the `-f `; for example, +this command is equivalent: ```bash hullcaster export > /path/to/output/file.opml @@ -81,92 +108,72 @@ hullcaster export > /path/to/output/file.opml ## Configuring hullcaster -If you want to change configuration settings, the sample `config.toml` file can be copied from [here](https://raw.githubusercontent.com/gilcu3/hullcaster/master/config.toml). Download it, edit it to your fancy, and place it in the following location: +If you want to change configuration settings, the sample `config.toml` file can +be copied from +[here](https://raw.githubusercontent.com/gilcu3/hullcaster/master/config.toml). +Download it, edit it to your fancy, and place it in the following location: ```bash # on Linux mkdir -p ~/.config/hullcaster cp config.toml ~/.config/hullcaster/ - -# on MacOS -mkdir -p ~/Library/Preferences/hullcaster -cp config.toml ~/Library/Preferences/hullcaster/ ``` -Or you can put `config.toml` in a place of your choosing, and specify the location at runtime: +Or you can put `config.toml` in a place of your choosing, and specify the +location at runtime: ```bash hullcaster -c /path/to/config.toml ``` -The sample file above provides comments that should walk you through all the available options. If any field does not appear in the config file, it will be filled in with the default value specified in those comments. The defaults are also listed below, for convenience. - -### Configuration options - -**download_path**: - -* Specifies where podcast episodes that are downloaded will be stored. -* Defaults: - * On Linux: $XDG_DATA_HOME/hullcaster/ or $HOME/.local/share/hullcaster/ - * On Mac: $HOME/Library/Application Support/hullcaster/ - * On Windows: C:\Users\\**username**\AppData\Local\hullcaster\ - -**play_command**: - -* Command used to play episodes. Use "%s" to indicate where file/URL will be entered to the command. Note that hullcaster does *not* include a native media player -- it simply passes the file path/URL to the given command with no further checking as to its success or failure. This process is started *in the background*, so be sure to send it to a program that has GUI controls of some kind so you have control over the playback. -* Default: "vlc %s" - -**download_new_episodes**: - -* Configures what happens when new episodes are found as podcasts are synced. Valid options: - * "always" will automatically download all new episodes; - * "ask-selected" will open a popup window to let you select which episodes to download, with all of them selected by default; - * "ask-unselected" will open a popup window to let you select with episodes to download, with none of them selected by default; - * "never" will never automatically download new episodes. -* Default: "ask-unselected" - -**simultaneous_downloads**: - -* Maximum number of files to download simultaneously. Setting this too high could result in network requests being denied. A good general guide would be to set this to the number of processor cores on your computer. -* Default: 3 - -**max_retries**: - -* Maximum number of times to retry connecting to a URL to sync a podcast or download an episode. -* Default: 3 - -#### Default keybindings - -| Key | Action | -| ------- | -------------- | -| ? | Open help window | -| Arrow keys / h,j,k,l | Navigate menus | -| Shift+K | Up 1/4 page | -| Shift+J | Down 1/4 page | -| PgUp | Page up | -| PgDn | Page down | -| a | Add new feed | -| q | Quit program | -| s | Synchronize selected feed | -| Shift+S | Synchronize all feeds | -| Enter / p | Play selected episode | -| m | Mark selected episode as played/unplayed | -| Shift+M | Mark all episodes as played/unplayed | -| d | Download selected episode | -| Shift+D | Download all episodes | -| x | Delete downloaded file | -| Shift+X | Delete all downloaded files | -| r | Remove selected feed/episode from list | -| Shift+R | Remove all feeds/episodes from list | -| 1 | Toggle played/unplayed filter | -| 2 | Toggle downloaded/undownloaded filter | - -**Note:** Actions can be mapped to more than one key (e.g., "Enter" and "p" both play an episode), but a single key may not do more than one action (e.g., you can't set "d" to both download and delete episodes). +The sample file above provides comments that should walk you through all the +available options. If any field does not appear in the config file, it will be +filled in with the default value specified in those comments. + +### Default key bindings + +| Key | Action | +|-----------------------------------|------------------------------------------| +| ? | Open help window | +| Arrow keys / h,j,k,l | Navigate menus | +| Shift+K | Up 1/4 page | +| Shift+J | Down 1/4 page | +| PgUp | Page up | +| PgDn | Page down | +| a | Add new feed | +| q | Quit program | +| s | Synchronize selected feed | +| Shift+S | Synchronize all feeds | +| Shift+A | Synchronize with gpodder | +| Enter / p | Play selected episode | +| m | Mark selected episode as played/unplayed | +| Shift+M | Mark all episodes as played/unplayed | +| d | Download selected episode | +| Shift+D | Download all episodes | +| x | Delete downloaded file | +| Shift+X | Delete all downloaded files | +| r | Remove selected feed/episode from list | +| Shift+R | Remove all feeds/episodes from list | +| 1 | Toggle played/unplayed filter | +| 2 | Toggle downloaded/not downloaded filter | + +**Note:** Actions can be mapped to more than one key (e.g., "Enter" and "p" both +play an episode), but a single key may not do more than one action (e.g., you +can't set "d" to both download and delete episodes). #### Customizable colors -You can set the colors in the app with either built-in terminal colors or (provided your terminal supports it) customizable colors as well. See the "colors" section in the [config.toml](https://github.com/gilcu3/hullcaster/blob/master/config.toml) for details about how to specify these colors! +You can set the colors in the app with either built-in terminal colors or +(provided your terminal supports it) customizable colors as well. See the +"colors" section in the +[config.toml](https://github.com/gilcu3/hullcaster/blob/master/config.toml) for +details about how to specify these colors! ## Syncing without the UI -Some users may wish to sync their podcasts automatically on a regular basis, e.g., every morning. The `hullcaster sync` subcommand can be used to do this without opening up the UI, and does a full sync of all podcasts in the database. This could be used to set up a cron job or systemd timer, for example. Please refer to the relevant documentation for these systems for setting it up on the schedule of your choice. +Some users may wish to sync their podcasts automatically on a regular basis, +e.g., every morning. The `hullcaster sync` subcommand can be used to do this +without opening up the UI, and does a full sync of all podcasts in the database. +This could be used to set up a cron job or systemd timer, for example. Please +refer to the relevant documentation for these systems for setting it up on the +schedule of your choice. diff --git a/config.toml b/config.toml index 7da6296..9a340e8 100644 --- a/config.toml +++ b/config.toml @@ -51,6 +51,40 @@ # mark_as_played_on_play = true +# Enable synchronization with a gpodder server +# Default: false + +# enable_sync = false + + +# Address of the gpodder server +# Default: None + +# sync_server = "https://gpodder.myserver.dev" + + +# Gpodder server username +# Default: None +# Required when enable_sync = true + +# sync_username = "myusername" + + +# Gpodder server password +# Default: None +# Required when enable_sync = true and sync_password_eval is None + +# sync_password = "mypassword" + + +# Gpodder server password eval +# Default: None +# Required when enable_sync = true and sync_password is None + +# sync_password_eval = "pass gpodder" + + + [keybindings] # Keybindings must be an array of one or more strings.