Create the base readme file

This commit is contained in:
Anas Elgarhy 2023-02-24 02:22:37 +02:00
parent 190d8befc6
commit eee582a393
No known key found for this signature in database
GPG key ID: 0501802A1D496528
10 changed files with 104 additions and 0 deletions

39
README.md Normal file
View file

@ -0,0 +1,39 @@
# cmus-notify: This program is a cmus status notification tool written in Rust, which can be easily configured and used for different purposes. It provides notifications for track changes, status changes, volume, playing mood and more
![track change notification](./screenshots/0.0.1_track_change_notify_1_cropped.png)
![another track change notification](./screenshots/0.0.1_track_change_notify_2_cropped.png)
![live action](./screenshots/0.0.1_live_action_2.gif)
> **Note:** This project is still in its early stages and is not yet ready for production use. It is currently being developed as a just-for-fun project. If you are interested in contributing, please feel free to open an issue or a pull request.
## Installation
- You can install the latest release from [crates.io][crates.io] using `cargo install cmus-notify`
- You can also install the latest version from the git repository using `cargo install --git https://github.com/anas-elgarhy/cmus-notify`
- Or if you use Arch Linux, you can install the [AUR package][aur package] using your favorite AUR helper. e.g. `yay -S notify-cmus`
## Usage
- Run `cmus-notify` in your terminal to start the program, the program will run in the background and will notify you about cmus status changes
- You can also run `cmus-notify --help` to see the available options, also you can see the available options in the [usage](./docs/usage.md)
- You also have the ability to configure the program using a configuration file, you basically have the same options as the command line arguments, but you can also use the configuration file to set the default values for the command line arguments, the default configuration file path is `~/.config/cmus-notify/config.toml`, you can also use the `--config` option to specify a custom configuration file path, the default config file will be created in `~/.config/cmus-notify/config.toml` if it doesn't exist
- The recommended way to use the program is to run it in the background when you start the `cmus` music player, you can do that by creating an alias for `cmus` in your shell configuration file, e.g. `alias cmus="cmus & cmus-notify --link"`, the `--link` option will link the `cmus-notify` process to the `cmus` process, so when you close `cmus` the `cmus-notify` process will also be terminated
## Development
- This project is written in Rust, so you need to have Rust installed on your system, you can install Rust using [rustup](https://rustup.rs/)
- This project, like most Rust projects, uses `cargo` as the build system. But to make my life easier I decided to use [just][just] as a task runner, so you need to install `just` using `cargo install just`
### Just tasks
- To build the project, run `just build` in the debug mode with all the features enabled
- To build the project in the release mode, run `just build--release` with all the features enabled
- To build and run the project, run `just run`, this will build the project in the debug mode and run it with the debug log level
- You can use `just c`, to run `cargo check` with all the features enabled
- You can use `just t`, to run `cargo test` with all the features enabled
- You can use `just show-help`, to show the help message for the `cmus-notify` program
- You can use `just coverage-report`, to generate a coverage report for the project, and open it in the default browser, the report will be generated in the `target/coverage` directory, this task requires [grcov][grcov] to be installed on your system
You can see the all the available tasks and aliases in the [justfile](./justfile), or by running `just --list`
[repo]: https://github.com/anas-elgarhy/cmus-notify
[crates.io]: https://crates.io/crates/cmus-notify
[aur package]: https://aur.archlinux.org/packages/notify-cmus/
[just]: https://github.com/casey/just
[grcov]:https://github.com/mozilla/grcov

65
docs/usage.md Normal file
View file

@ -0,0 +1,65 @@
# Command-Line Help for `cmus-notify`
This document contains the help content for the `cmus-notify` command-line program.
**Command Overview:**
* [`cmus-notify`↴](#cmus-notify)
## `cmus-notify`
**Usage:** `cmus-notify [OPTIONS] [BODY]`
###### **Arguments:**
* `<BODY>` — The body of the notification
###### **Options:**
* `-t`, `--timeout <TIMEOUT>` — The notification timeout, in seconds
* `-p`, `--persistent` — Make the notification persistent, i.e. not disappear after a timeout (you can dismiss it manually)
* `-c`, `--cover` — Show the track cover in the notification, if available
* `-i`, `--icon <NOTIFICATION_STATIC_COVER>` — The static icon to use for the notification, it not effective if the track cover is shown, but if the cover is not available or you disabled it, this icon will be used
* `-w`, `--cover-path <COVER_PATH_TEMPLATE>` — The path to look for the cover image, if not given, the cover will be searched in the track's directory for an image file with the name "cover"
* `-y`, `--lyrics-path <LYRICS_PATH>` — The lyrics file path, if not given, the lyrics will be searched in the track's directory for a text file with the name "lyrics", or with the same name as the track
* `-d`, `--depth <DEPTH>` — The maximum path depth to search for the cover and lyrics files, if the files are not found in the track's directory, or the directory specified by the `--cover-path` or `--lyrics-path`* options, the program will search in the parent directory, and so on, until the maximum depth is reached
* `-a`, `--app-name <APP_NAME>` — The name of the app to use for the notification
* `-s`, `--summary <SUMMARY>` — The summary of the notification
* `-b`, `--cmus-remote-bin <CMUS_REMOTE_BIN_PATH>` — The cmus-remote binary path, if not given, the program will search for it in the PATH environment variable
* `-k`, `--cmus-socket <CMUS_SOCKET_ADDRESS>` — The cmus socket address, if not given, the program will use the default socket address, which is "$XDG_RUNTIME_DIR/cmus-socket"
* `-x`, `--socket-password <CMUS_SOCKET_PASSWORD>` — The cmus socket password, if any
* `-r`, `--interval <INTERVAL>` — The interval to request the cmus status, in milliseconds
* `-l`, `--link` — Link the program with cmus, if the cmus are not running, the program will exit
* `-u`, `--force-use-external-cover` — Force the program to use the external cover file, if available, and not even try to get the cover from the track's metadata. this is useful if you have a cover file with a better quality than the cover in the track's metadata
* `-m`, `--force-use-external-lyrics` — Fotrce the program to use the external lyrics file, if available, and not even try to get the lyrics from the track's metadata
* `-n`, `--no-use-external-cover` — No use the external cover file, even if it's available and the track's metadata doesn't have a cover
* `-o`, `--no-use-external-lyrics` — No use the external lyrics file, even if it's available and the track's metadata doesn't have a lyrics
* `-g`, `--show-player-notifications` — Show the player notifications, like if you change the shuffle mode, or the repeat mode, or the volume
* `-B`, `--volume-notification-body <VOLUME_NOTIFICATION_BODY>` — The volume change notification body. you can use the placeholders like "{volume}" in the body, it will be replaced with the shuffle mode
* `-E`, `--volume-notification-summary <VOLUME_NOTIFICATION_SUMMARY>` — The volume change notification summary
* `-T`, `--volume-notification-timeout <VOLUME_NOTIFICATION_TIMEOUT>` — The time out of the volume change notification, in seconds
* `-S`, `--shuffle-notification-body <SHUFFLE_NOTIFICATION_BODY>` — The shuffle mode change notification body. you can use the placeholders like "{shuffle}" in the body, it will be replaced with the shuffle mode
* `-U`, `--shuffle-notification-summary <SHUFFLE_NOTIFICATION_SUMMARY>` — The shuffle mode change notification summary. you can use the placeholders like "{shuffle}" in the summary, it will be replaced with the shuffle mode
* `-Y`, `--shuffle-notification-timeout <SHUFFLE_NOTIFICATION_TIMEOUT>` — The time out of the shuffle mode change notification, in seconds
* `-R`, `--repeat-notification-body <REPEAT_NOTIFICATION_BODY>` — The repeat mode change notification body. you can use the placeholders like "{repeat}" in the body, it will be replaced with the repeat mode
* `-G`, `--repeat-notification-summary <REPEAT_NOTIFICATION_SUMMARY>` — The repeat mode change notification summary. you can use the placeholders like "{repeat}" in the summary, it will be replaced with the repeat mode
* `-H`, `--repeat-notification-timeout <REPEAT_NOTIFICATION_TIMEOUT>` — The time out of the repeat mode change notification, in seconds
* `-A`, `--aaa-mode-notification-body <AAA_MODE_NOTIFICATION_BODY>` — The aaa mode change notification body. you can use the placeholders like "{aaa_mode}" in the body, it will be replaced with the aaa mode
* `-D`, `--aaa-mode-notification-summary <AAA_MODE_NOTIFICATION_SUMMARY>` — The aaa mode change notification summary. you can use the placeholders like "{aaa_mode}" in the summary, it will be replaced with the aaa mode
* `-F`, `--aaa-mode-notification-timeout <AAA_MODE_NOTIFICATION_TIMEOUT>` — The time out of the aaa mode change notification, in seconds
* `-L`, `--lyrics-notification-body <LYRICS_NOTIFICATION_BODY>` — The lyrics notification body, if you want to show the lyrics separate notification. you can use the placeholders like "{lyrics}" in the body, it will be replaced with the lyrics
* `-M`, `--lyrics-notification-summary <LYRICS_NOTIFICATION_SUMMARY>` — The lyrics notification summary, if you want to show the lyrics separate notification. you can use the placeholders like "{lyrics}" in the summary, it will be replaced with the lyrics
* `-O`, `--status-notification-body <STATUS_NOTIFICATION_BODY>` — The status change notification body. you can use the placeholders like "{status}" in the body, it will be replaced with the aaa mode
* `-P`, `--status-notification-summary <STATUS_NOTIFICATION_SUMMARY>` — The status change notification summary. you can use the placeholders like "{status}" in the summary, it will be replaced with the aaa mode
* `-Q`, `--status-notification-timeout <STATUS_NOTIFICATION_TIMEOUT>` — The time out of the status change notification, in seconds
* `--markdown-help`
<hr/>
<small><i>
This document was generated automatically by
<a href="https://crates.io/crates/clap-markdown"><code>clap-markdown</code></a>.
</i></small>

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.1 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.2 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 301 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 143 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.2 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 126 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.2 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 100 KiB