Skip to content

Commit

Permalink
minor README
Browse files Browse the repository at this point in the history
  • Loading branch information
gilcu3 committed Mar 14, 2024
1 parent 1eddb97 commit 8b4d098
Showing 1 changed file with 28 additions and 23 deletions.
51 changes: 28 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,38 +1,38 @@
<div align="center"><img alt="shellcaster logo: Ferris the crab with headphones" src="https://raw.githubusercontent.com/gilcu3/shellcaster/master/img/shellcaster-logo_smol.png"/></div>

# Note
# Shellcaster

This is a fork of the original [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.
![shellcaster logo: Ferris the crab with headphones](https://raw.githubusercontent.com/gilcu3/shellcaster/master/img/shellcaster-logo_smol.png)

# Shellcaster

Shellcaster 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.

<div align="center"><img alt="screenshot of shellcaster" src="https://raw.githubusercontent.com/gilcu3/shellcaster/master/img/screenshot.png"/></div>
![screenshot of shellcaster](https://raw.githubusercontent.com/gilcu3/shellcaster/master/img/screenshot.png)

## Installing shellcaster
## Note

This is a fork of the original [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.

## Installing shellcaster

### On Linux distributions and MacOS

Currently the only option is to build from source.

First, ensure you have installed the necessary dependencies:

* rust
* gcc
* pkg-config
* libsqlite3-dev
* rust
* gcc
* pkg-config
* libsqlite3-dev

**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 shellcaster (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 shellcaster (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 shellcaster (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 shellcaster (disabled by default), `pkg-config` and `libsqlite3-dev` are not necessary.

Next, there are two options for compiling the program:
Next, there are two options for compiling the program:

1. You can install the latest version of the binary directly from crates.io with one command:
- You can install the latest version of the binary directly from crates.io with one command:

```bash
# for MacOS or Linux
Expand All @@ -42,7 +42,7 @@ sudo cargo install shellcaster --no-track --root "/usr/local" # add or remove a
cargo install shellcaster --no-track --root "$HOME/.local"
```

2. You can clone the Github repo and compile it yourself:
- You can clone the Github repo and compile it yourself:

```bash
git clone https://github.com/gilcu3/shellcaster.git
Expand Down Expand Up @@ -87,7 +87,7 @@ cp target/release/shellcaster ~/.local/bin/

## Running shellcaster

Easy peasy! In your terminal, run:
Easy-peasy! In your terminal, run:

```bash
shellcaster
Expand Down Expand Up @@ -146,29 +146,34 @@ The sample file above provides comments that should walk you through all the ava
### Configuration options

**download_path**:

* Specifies where podcast episodes that are downloaded will be stored.
* Defaults:
* On Linux: $XDG_DATA_HOME/shellcaster/ or $HOME/.local/share/shellcaster/
* On Mac: $HOME/Library/Application Support/shellcaster/
* On Windows: C:\Users\\**username**\AppData\Local\shellcaster\

**play_command**:

* Command used to play episodes. Use "%s" to indicate where file/URL will be entered to the command. Note that shellcaster 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.
* "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

Expand Down Expand Up @@ -206,4 +211,4 @@ You can set the colors in the app with either built-in terminal colors or (provi

## Syncing without the UI

Some users may wish to sync their podcasts automatically on a regular basis, e.g., every morning. The `shellcaster 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 `shellcaster 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.

0 comments on commit 8b4d098

Please sign in to comment.