From b303a2a54119ba2d68df637ef0d1c0c3343e02f8 Mon Sep 17 00:00:00 2001 From: "J. Gerhards" Date: Wed, 11 Jun 2025 17:56:26 +0200 Subject: [PATCH 1/5] Refactor: rename every instance of mpDris to mpdris Since the package in Cargo.toml and the AUR is called mpdris it doesn't make much sense to make the actual name of the application mpDris, especially since every other file is also all lowercase. --- Cargo.toml | 2 +- README.md | 44 ++++++++++++++++++------------------ resources/sample.mpdris.conf | 8 +++---- src/args.rs | 2 +- 4 files changed, 28 insertions(+), 28 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index d4e67b2..af3c8a1 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -5,7 +5,7 @@ version = "1.2.0" edition = "2024" authors = [ "jasger9000 | jasger_" ] license = "MIT" -repository = "https://github.com/jasger9000/mpDris" +repository = "https://github.com/jasger9000/mpdris" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html diff --git a/README.md b/README.md index 9632e7c..4a8bd91 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ -[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/jasger9000/mpDris/?tab=MIT-1-ov-file) -[![build](https://github.com/jasger9000/mpDris/actions/workflows/build.yml/badge.svg)](https://github.com/jasger9000/mpDris/actions/workflows/build.yml) -[![GitHub release](https://img.shields.io/github/release/jasger9000/mpDris/all.svg)](https://github.com/jasger9000/mpDris/releases) -[![Issues](https://img.shields.io/github/issues/jasger9000/mpDris.svg)](https://github.com/jasger9000/mpDris/issues) +[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/jasger9000/mpdris/?tab=MIT-1-ov-file) +[![build](https://github.com/jasger9000/mpdris/actions/workflows/build.yml/badge.svg)](https://github.com/jasger9000/mpdris/actions/workflows/build.yml) +[![GitHub release](https://img.shields.io/github/release/jasger9000/mpdris/all.svg)](https://github.com/jasger9000/mpdris/releases) +[![Issues](https://img.shields.io/github/issues/jasger9000/mpdris.svg)](https://github.com/jasger9000/mpdris/issues) -# MpDris +# mpdris A lightweight application that implements the media player D-Bus interface [MPRIS](https://wiki.archlinux.org/title/MPRIS) for the [Music Player Daemon (MPD)](https://musicpd.com). @@ -50,9 +50,9 @@ You can either build the AUR-package yourself, as detailed below, or use your fa | Type | AUR | GitHub | | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | -| [Default](a "Compile yourself from release source tarball") | [![AUR Version](https://img.shields.io/aur/version/mpdris)](https://aur.archlinux.org/packages/mpdris) | [GitHub Link](https://github.com/jasger9000/mpDris-aur/tree/master) | -| [Binary](a "Download prebuilt release binaries") | [![AUR Version](https://img.shields.io/aur/version/mpdris-bin)](https://aur.archlinux.org/packages/mpdris-bin) | [GitHub Link](https://github.com/jasger9000/mpDris-aur/tree/pkg-bin) | -| [Git](a "Download & compile from git source") | [![AUR Version](https://img.shields.io/aur/version/mpdris-git)](https://aur.archlinux.org/packages/mpdris-git) | [GitHub Link](https://github.com/jasger9000/mpDris-aur/tree/pkg-git) | +| [Default](a "Compile yourself from release source tarball") | [![AUR Version](https://img.shields.io/aur/version/mpdris)](https://aur.archlinux.org/packages/mpdris) | [GitHub Link](https://github.com/jasger9000/mpdris-aur/tree/master) | +| [Binary](a "Download prebuilt release binaries") | [![AUR Version](https://img.shields.io/aur/version/mpdris-bin)](https://aur.archlinux.org/packages/mpdris-bin) | [GitHub Link](https://github.com/jasger9000/mpdris-aur/tree/pkg-bin) | +| [Git](a "Download & compile from git source") | [![AUR Version](https://img.shields.io/aur/version/mpdris-git)](https://aur.archlinux.org/packages/mpdris-git) | [GitHub Link](https://github.com/jasger9000/mpdris-aur/tree/pkg-git) | #### Build the AUR-package manually 1. Clone the AUR package repository and cd into the directory: @@ -74,7 +74,7 @@ You can either build the AUR-package yourself, as detailed below, or use your fa ### Build the application yourself 1. Clone this repository ```bash - git clone https://github.com/jasger9000/mpDris + git clone https://github.com/jasger9000/mpdris.git ``` 2. Build the project with ```bash @@ -88,22 +88,22 @@ You can either build the AUR-package yourself, as detailed below, or use your fa ``` ### Install using release binary -1. Go to the [release tab](https://github.com/jasger9000/mpDris/releases) 2. Download the correct binary for your architecture +1. Go to the [release tab](https://github.com/jasger9000/mpdris/releases) - If you don't know what your architecture is, you can find out by running `lscpu` 3. Copy the file to `/usr/local/bin` and rename it to `mpdris` 4. Add the execute permission to the file with ```bash chmod +x /usr/local/bin/mpdris ``` -5. Download and move [mpdris.service](https://github.com/jasger9000/mpDris/blob/main/resources/mpdris.service) to `/usr/local/lib/systemd/user` (You might have to create that directory first) +5. Download and move [mpdris.service](https://github.com/jasger9000/mpdris/blob/main/resources/mpdris.service) to `/usr/local/lib/systemd/user` (You might have to create that directory first) 6. Enable the service to start it with MPD ```bash systemctl --user enable mpdris.service ``` ## Configuration -You can configure mpDris using the configuration file or using command-line arguments. +You can configure mpdris using the configuration file or using command-line arguments. The config file should either be located in `$XDG_CONFIG_HOME/mpdris/mpdris.conf` or `~/.config/mpdris/mpdris.conf` > [!NOTE] @@ -111,9 +111,9 @@ The config file should either be located in `$XDG_CONFIG_HOME/mpdris/mpdris.conf > deprecated and may be removed in a future update. The config file has the following options: -- addr: The IP address mpDris uses to connect to MPD (default: 127.0.0.1) -- port: The port mpDris uses to connect to MPD (default: 6600) -- retries: Defines the amount of times mpDris retries to establish a connection to MPD (default: 3) +- addr: The IP address mpdris uses to connect to MPD (default: 127.0.0.1) +- port: The port mpdris uses to connect to MPD (default: 6600) +- retries: Defines the amount of times mpdris retries to establish a connection to MPD (default: 3) - music_directory: The directory in which MPD searches for Music (default: `~/Music`) - cover_directory: The dedicated directory to where your covers are stored. (default: `~/Music/covers`) @@ -123,18 +123,18 @@ This directory will be searched for image files that correspond to the currently #### Example: Let's say you have a user who stores their Music in `~/Music` and set their `cover_directory` to be in `~/Music/Pictures/songcovers`.
If they now play the song `Resurrections.mp3` located in `~/Music/Celeste`,
-mpDris will search in `~/Pictures/songcovers/Celeste/` for a file named Resurrections with one of the following file extensions:
+mpdris will search in `~/Pictures/songcovers/Celeste/` for a file named Resurrections with one of the following file extensions:
`jpg`, `jpeg`, `png`, `webp`, `avif`, `jxl`, `bmp`, `gif`, `heif` and `heic`. Alternatively if the song is located in a sub-directory, you can name a cover file the same name as the directory and it will be used for every song in that directory.
-So sticking with the example from above, mpDris will search for a file in `~/Pictures/songcovers/` +So sticking with the example from above, mpdris will search for a file in `~/Pictures/songcovers/` named Celeste with one of the above listed extensions. ### music_directory Like cover_directory, this directory can also be used to find covers. -MpDris will search the following paths for song covers, using the first one it finds: +mpdris will search the following paths for song covers, using the first one it finds: - `$music_directory/$song_path/$filename.$ext` - `$music_directory/$song_path/cover.$ext` @@ -142,7 +142,7 @@ where `$song_path` the path up to the song from `$music_directory`, `$filename` `$ext` one of the image extensions listed under cover_directory. #### Example -If you have the song `Resurrections.mp3` in `/home/johndoe/Music/Celeste/`, mpDris will search for a cover like this: +If you have the song `Resurrections.mp3` in `/home/johndoe/Music/Celeste/`, mpdris will search for a cover like this: - `/home/johndoe/Music/Celeste/Resurrections.jpg` - `/home/johndoe/Music/Celeste/Resurrections.png`
... @@ -164,12 +164,12 @@ If you have the song `Resurrections.mp3` in `/home/johndoe/Music/Celeste/`, mpDr ## Contributing Contributions are always welcome! -If you feel there's something missing/wrong/something that could be improved please open an [issue](https://github.com/jasger9000/mpDris/issues).
-Or if you want to add something yourself, just [open a pull request](https://github.com/jasger9000/mpDris/pulls) and I will have a look at it as soon as I can. +If you feel there's something missing/wrong/something that could be improved please open an [issue](https://github.com/jasger9000/mpdris/issues).
+Or if you want to add something yourself, just [open a pull request](https://github.com/jasger9000/mpdris/pulls) and I will have a look at it as soon as I can. ## Licence -The Project is Licensed under the [MIT Licence](https://github.com/jasger9000/mpDris/?tab=MIT-1-ov-file) +The Project is Licensed under the [MIT Licence](https://github.com/jasger9000/mpdris/?tab=MIT-1-ov-file) ## Authors diff --git a/resources/sample.mpdris.conf b/resources/sample.mpdris.conf index e749115..9fad156 100644 --- a/resources/sample.mpdris.conf +++ b/resources/sample.mpdris.conf @@ -16,17 +16,17 @@ # It is very likely that this is just ~/Music # Note: while there is shell escaping, the brace syntax (${varname}) is as of v.1.2.0 not supported # -# mpDris will search this directory for covers like this: # - $music_directory/$song_path/$filename.$ext # - $music_directory/$song_path/cover.$ext # # $ext can be one of the following values: jpg, jpeg, png, webp, avif, jxl, bmp, gif, heif, heic # For an alternative cover path and more detail on covers, please read the section on cover_directory below. +# mpdris will search this directory for covers like this: # # music_directory = "~/Music" # The dedicated directory to where your covers are stored. -# mpDris will search this directory for covers like this: +# mpdris will search this directory for covers like this: # $cover_directory/$song_path/$filename.$ext # # $ext can be one of the following values: jpg, jpeg, png, webp, avif, jxl, bmp, gif, heif, heic @@ -34,12 +34,12 @@ # Example: # Let's say you have a user who stores their Music in ~/Music and set their cover_directory # to be in ~/Music/Pictures/songcovers. -# If they now play the song Resurrections.mp3 located in ~/Music/Celeste, mpDris will search in +# If they now play the song Resurrections.mp3 located in ~/Music/Celeste, mpdris will search in # ~/Pictures/songcovers/Celeste/ for a file named Resurrections with one of the above mentioned file extensions. # # Alternatively if the song is located in a sub-directory, you can name a cover file the same name as the directory # and it will be used for every song in that directory. -# So sticking with the example from above, mpDris will search for a file named Celeste in cover_directory +# So sticking with the example from above, mpdris will search for a file named Celeste in cover_directory # with one of the above listed extensions. # # cover_directory = "~/Music/covers" diff --git a/src/args.rs b/src/args.rs index cc485b9..b98d089 100644 --- a/src/args.rs +++ b/src/args.rs @@ -17,7 +17,7 @@ pub struct Args { /// the ip address over which to connect to mpd #[argh(option, short = 'a')] pub addr: Option, - /// amount of times mpDris tries to reconnect to mpd before exiting. Set to -1 to retry inifinite times + /// number of times mpdris tries to reconnect to mpd before exiting. Set to -1 to retry infinite times #[argh(option, short = 'r')] pub retries: Option, /// path to config file to use instead of the default From 57e4232034ac5d265c87aba5f7a169a11728ab31 Mon Sep 17 00:00:00 2001 From: "J. Gerhards" Date: Wed, 11 Jun 2025 18:07:59 +0200 Subject: [PATCH 2/5] Refactor: Redwrite the cover section in the README Rewrite the cover section of the README to better explain how mpdris searches for covers. --- README.md | 45 +++++++++++++++++---------------------------- 1 file changed, 17 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 4a8bd91..30c5c32 100644 --- a/README.md +++ b/README.md @@ -117,39 +117,28 @@ The config file has the following options: - music_directory: The directory in which MPD searches for Music (default: `~/Music`) - cover_directory: The dedicated directory to where your covers are stored. (default: `~/Music/covers`) -### cover_directory -This directory will be searched for image files that correspond to the currently playing song to display as cover art. +### Covers - cover_directory & music_directory +mpdris will search the configured cover and music directory for image files that correspond to the currently playing song to display as cover art. -#### Example: -Let's say you have a user who stores their Music in `~/Music` and set their `cover_directory` to be in `~/Music/Pictures/songcovers`.
-If they now play the song `Resurrections.mp3` located in `~/Music/Celeste`,
-mpdris will search in `~/Pictures/songcovers/Celeste/` for a file named Resurrections with one of the following file extensions:
-`jpg`, `jpeg`, `png`, `webp`, `avif`, `jxl`, `bmp`, `gif`, `heif` and `heic`. +Paths will be searched in the following order, trying every extension before moving to the next one: +— $cover_directory/$song_path/$filename.$ext +— $cover_directory/$song_path/$parent_name.$ext +— $music_directory/$song_path/$filename.$ext +— $music_directory/$song_path/cover.$ext -Alternatively if the song is located in a sub-directory, you can name a cover file the same name as the directory -and it will be used for every song in that directory.
-So sticking with the example from above, mpdris will search for a file in `~/Pictures/songcovers/` -named Celeste with one of the above listed extensions. +`$ext` can be one of the following values: jpg, jpeg, png, webp, avif, jxl, bmp, gif, heif and heic.
+`$song_path` is the file path in the music directory leading up to the current song.
+`$parent_name` is the name of the parent directory of the current song. (`$parent_name` is excluded from $song_path when both are used)
+#### Example +Let's say you have a user who stores their music in `~/Music` and sets their cover_directory to be in `~/Pictures/songcovers`. +If they now play the song `Resurrections.mp3` located in `~/Music/Celeste`, mpdris will search in `~/Pictures/songcovers/Celeste/` for a file named Resurrections with one of the above-mentioned file extensions.
+If it cannot find it there, it will move to the next path. -### music_directory -Like cover_directory, this directory can also be used to find covers. -mpdris will search the following paths for song covers, using the first one it finds: -- `$music_directory/$song_path/$filename.$ext` -- `$music_directory/$song_path/cover.$ext` - -where `$song_path` the path up to the song from `$music_directory`, `$filename` the underlying filename of the song and -`$ext` one of the image extensions listed under cover_directory. +If the song is located in a subdirectory of the music directory, you can name a cover file the same name as the directory (denoted as `$parent_name` above), and it will be used for every song in that directory. +So sticking with the example from above, mpdris will search for a file named Celeste in cover_directory with one of the above-listed extensions. +If the song was one level deeper, so, for example, `~/Music/some/long/path/Celeste/Resurrections.mp3`, mpdris would look for the cover with this path: `~/Pictures/songcovers/some/long/path/Celeste.$ext` -#### Example -If you have the song `Resurrections.mp3` in `/home/johndoe/Music/Celeste/`, mpdris will search for a cover like this: -- `/home/johndoe/Music/Celeste/Resurrections.jpg` -- `/home/johndoe/Music/Celeste/Resurrections.png`
-... -- `/home/johnode/Music/Celeste/cover.jpg` -- `/home/johnode/Music/Celeste/cover.png`
-... -- `/home/johndoe/Music/Celeste/cover.heic` ## Roadmap - [x] implement base interface From a36621cf09f3735882f4f3cea3acb19a968be283 Mon Sep 17 00:00:00 2001 From: "J. Gerhards" Date: Wed, 11 Jun 2025 19:47:55 +0200 Subject: [PATCH 3/5] add man pages add two man pages to document mpdris itself and mpdris.conf --- README.md | 2 +- resources/man/man1/mpdris.1 | 309 +++++++++++++++++++++++++++++++ resources/man/man5/mpdris.conf.5 | 114 ++++++++++++ 3 files changed, 424 insertions(+), 1 deletion(-) create mode 100644 resources/man/man1/mpdris.1 create mode 100644 resources/man/man5/mpdris.conf.5 diff --git a/README.md b/README.md index 30c5c32..1da2a4d 100644 --- a/README.md +++ b/README.md @@ -144,7 +144,7 @@ If the song was one level deeper, so, for example, `~/Music/some/long/path/Celes - [x] implement base interface - [x] implement player interface - [x] add control functionality -- [ ] add a manpage +- [x] add a manpage - [ ] add ffmpeg cover support - [ ] implement tracklist interface diff --git a/resources/man/man1/mpdris.1 b/resources/man/man1/mpdris.1 new file mode 100644 index 0000000..938e6c8 --- /dev/null +++ b/resources/man/man1/mpdris.1 @@ -0,0 +1,309 @@ +.\" Manpage for mpdris. +.\" Contact g1.jasger@gmail.com to correct errors or typos. +.TH MPDRIS 1 "2025\-06\-09" "mpdris 1.2.1" "mpdris man page" +.AU J. Gerhards +.SH NAME +mpdris \- a bridge between MPD and MPRIS for music control +.SH SYNOPSIS +.B mpdris +.RB [ \-p\ \fI ] +.RB [ \-a\ \fI ] +.RB [ \-r\ \fI ] +.RB [ \-\-config\ \fI ] +.RB [ \-\-level\ \fI ] +.RB [ \-\-daemon ] +.RB [ \-\-service ] +.SH DESCRIPTION +mpdris is a lightweight application that implements the media player D-Bus interface MPRIS for the Music Player Daemon (MPD). +This makes it possible to control your music through other software that implements the MPRIS standard (desktop environments and such). +.br +On startup mpdris first initializes the logging facility (logs to stdout). +Afterwards, mpdris looks for the configuration file +.RB (see\ FILES ). +If it cannot find it, it will start with the default values (or the ones given as arguments +.RB (see\ OPTIONS )). +and write the loaded values to the default location. +.br +Next, mpdris will connect to MPD; on a successful connection, it will then register a D-Bus interface. +If the name of the interface is already taken on the bus (for example, because another instance is already running), mpdris will immediately exit. +Otherwise, mpdris is then ready and will listen to interrupt signals. + +mpdris will override the IP address and port over which to connect to MPD set in the config with the values of +.B $MPD_HOST +and +.BR $MPD_PORT , +which itself will be overridden by the command line arguments. +.br +This creates the following order of importance, starting with the least and ending with the most important: +.br +\(em Config values +.br +\(em Environment variables +.br +\(em Command line arguments + +.TP +Covers \- cover_directory & music_directory +mpdris will search the configured cover and music directory for image files that correspond to the currently playing song to display as cover art. + +Paths will be searched in the following order, trying every extension before moving to the next one: +.br +\(em +.IR $cover_directory / $song_path / $filename \&. $ext +.br +\(em +.IR $cover_directory / $song_path / $parent_name \&. $ext +.br +\(em +.IR $music_directory / $song_path / $filename \&. $ext +.br +\(em +.IR $music_directory / $song_path /cover\&. $ext + +.I $ext +can be one of the following values: +.BR jpg , +.BR jpeg , +.BR png , +.BR webp , +.BR avif , +.BR jxl , +.BR bmp , +.BR gif , +.BR heif +and +.BR heic . +.br +.I $song_path +is the file path in the music directory leading up to the current song. +.br +.I $parent_name +is the name of the parent directory of the current song. +.RI ( $parent_name +is excluded from +.I $song_path +when both are used) + +Example: +.br +Let's say you have a user who stores their music in +.B ~/Music +and sets their +.B cover_directory +to be in +.BR ~/Pictures/songcovers . +.br +If they now play the song +.B Resurrections\&.mp3 +located in +.BR ~/Music/Celeste , +mpdris will search in +.B ~/Pictures/songcovers/Celeste/ +for a file named +.B \%Resurrections +with one of the above-mentioned file extensions. +.br +If it cannot find it there, it will move to the next path. + +If the song is located in a subdirectory of the music directory, you can name a cover file the same name as the directory +.RI (denoted\ as\ $parent_name\ above), +and it will be used for every song in that directory. +.br +So sticking with the example from above, mpdris will search for a file named +.B Celeste +in +.B cover_directory +with one of the above-listed extensions. +.br +If the song was one level deeper, so, for example, +.BR ~/Music/some/long/path/Celeste/Resurrections\&.mp3 , +mpdris would look for the cover with this path: +.B ~/Pictures/songcovers/some/long/path/Celeste\&.\fI$ext +.SH EXAMPLES +.EX +.TP +.B mpdris +Start mpdris with the default settings, outputting logs to stdout/stderr +.TP +.BI mpdris\ -p\ 6601\ -a\ 192.168.1.10 +Connect to MPD on the port \fI6601\fR over the IP address \fI192.168.1.10 +.TP +.BI mpdris\ --retries\ 5 +Set attempts to reconnect to MPD to \fI5\fR before mpdris exits +.TP +.BI mpdris\ --config\ /home/johndoe/configs/mpdris.conf +Use a custom configuration file located at \fI/home/johndoe/configs/mpdris.conf +.TP +.BI mpdris\ --level\ debug +Run mpdris with the logging verbosity increased to the \fIdebug\fR level +.TP +.B mpdris --daemon +Run mpdris as a daemon in the background +.EE +.SH OPTIONS +.TP +.BR \-v ,\ \-\-version +display the version and exit. +.TP +.BI \-p\ \fR,\ \-\-port\ +the port over which to connect to mpd. +.TP +.BI \-a\ \fR,\ \-\-addr\ +the ip address over which to connect to mpd. +.TP +.BI \-r\ \fR,\ \-\-retries\ +amount of times mpdris tries to reconnect to MPD before exiting. +.br +Set to \fB-1\fR to retry infinite times. +.TP +.BI \-\-config\ +path to config file to use instead of the default. +.TP +.BI \-\-level\ +the logging level/verbosity to use. May be one of: +.BR trace , +.BR debug , +.BR info , +.BR warn , +.BR error +.TP +.B \-\-daemon +When set, mpdris will try to fork into a daemon upon launch. +Additionally, mpdris will close stdout, stdin, and sterr. +.br +Upon receiving a +.B SIGHUP +signal, mpdris will reload the config. +.TP +.B \-\-service +should only be set when started through a systemd service. +.br +mpdris will try to load libsystemd in order to be able to notify systemd of its status. +Failing to find/load the library will result in mpdris immediately exiting. +.br +As with the +.B \-\-daemon +flag, upon receiving a +.B SIGHUP +signal, mpdris will reload the config. +.TP +.BR \-h ,\ \-\-help +display usage information +.SH EXIT STATUS +.IP "Status code: 0" +\(em When the +.B \-\-version +flag was given, after displaying the version +.br +\(em When the application exits gracefully after being given an exit signal +.br +\(em When the +.B \-\-daemon +flag was given, the parent process exits with status code 0 after the fork +.IP "Status code: 1" +\(em When failing to set up the signal handler +.br +\(em When failing to load the config +.br +\(em When receiving a +.B SIGQUIT +and failing to dump the core +.br +\(em When receiving a second exit signal while trying to shut down gracefully +.IP "Status code: 101" +\(em When +.B $HOME +is not set or contains non-UTF-8 characters +.br +\(em In the event, that the variable holding the config was written to before loading the config +.br +\(em When failing to load libsystemd +.br +\(em When failing to create a valid trackid path for the dbus interface +.br +\(em When an internal channel to notify of MPD changes gets closed +.br +\(em When failing to send an exit signal to itself after using all retries to connect to MPD +.br +\(em When failing to get the current UTC offset +.br +\(em When failing to set the logging facility +.SH ENVIRONMENT +.TP +.B HOME +Used to get the path of the configuration file when +.B $XDG_CONFIG_HOME +is not set +.RB (see\ FILES ). +.br +Additionally, paths beginning with tilde ('~') +in the config file are replaced with +.BR $HOME . +.br +It is also used to set the default values for the +.BR music_dir\ and\ cover_dir\ (see\ FILES ). +.TP +.B XDG_CONFIG_HOME +Used to get the path of the configuration file +.RB (see\ FILES ). +.TP +.B MPD_HOST +The host/IP address over which mpdris will try to connect to MPD. +In the case that a host instead of an IP address is given, mpdris will do a DNS lookup to resolve the address. + +While +.B $MPD_HOST +overrides the +.B addr +value in the config, it does not override the command line arguments. +.TP +.B MPD_PORT +The port over which mpdris will try to connect to MPD. + +While +.B $MPD_PORT +overrides the +.B port +value in the config, it does not override the command line arguments. +.SH FILES +.TP +.I $XDG_CONFIG_HOME/mpdris/mpdris.conf\fR,\fI $HOME/.config/mpdris/mpdris.conf +The mpdris configuration file. +.br +The format and valid entries are detailed in +.MR mpdris\&.conf 5 . +.br +A sample config can be found in +.B /usr/share/doc/mpdris/sample.mpdris.conf +.TP +.I $HOME/Music +The default music directory +.RB (see\ DESCRIPTION ). +.br +The path can be changed in the configuration file (see +.MR mpdris\&.conf 5 ). +.TP +.I $HOME/Music/covers +The default cover directory +.RB (see\ DESCRIPTION ). +.br +The path can be changed in the configuration file (see +.MR mpdris\&.conf 5 ). +.SH STANDARDS +MPRIS D-Bus Interface Specification Version 2.2 +.SH BUGS +Please report any issues and bugs to +.UR https://github.com/jasger9000/mpdris/issues +.UE +.SH AUTHORS +J. Gerhards (\c +.MT g1.jasger@gmail.com +.ME ")" +& Contributors + +.UR https://github.com/jasger9000/mpdris/graphs/contributors +GitHub contributor graph +.UE +.SH SEE ALSO +.MR mpdris\&.conf 5 , +.MR mpd 1 diff --git a/resources/man/man5/mpdris.conf.5 b/resources/man/man5/mpdris.conf.5 new file mode 100644 index 0000000..a4815dd --- /dev/null +++ b/resources/man/man5/mpdris.conf.5 @@ -0,0 +1,114 @@ +.\" Manpage for the mpdris configuration file mpdris.conf. +.\" Contact g1.jasger@gmail.com to correct errors or typos. +.TH MPDRIS\&.CONF 5 "2025\-06\-09" "mpdris 1.2.1" "mpdris\&.conf man page" +.AU J. Gerhards +.SH NAME +mpdris\&.conf \- mpdris configuration file +.SH SYNOPSIS +.sp +$XDG_CONFIG_HOME/mpdris/mpdris\&.conf, $HOME/\&.config/mpdris/mpdris\&.conf + +/usr/share/doc/mpdris/sample\&.mpdris\&.conf +.SH DESCRIPTION +mpdris\&.conf is the configuration file for +.BR mpdris (1). +If not specified as a command line argument, mpdris searches for it at +.B $XDG_CONFIG_HOME/mpdris/mpdris\&.conf\fR, +if +.B $XDG_CONFIG_HOME +is defined. If not, mpdris will instead look at +.B $HOME/\&.config/mpdris/mpdris\&.conf\fR. +.br +If it also can't find it there, it will load the default values and write them to the selected location. + +The configuration is written in the TOML format, meaning: +.br +# This is a comment + +this_is_a_value = 6600 + +[section] +.br +key = "and this is a value in a section" # this is also a valid comment + +For settings that specify a file path, the tilde ('~') is expanded to +.B $HOME\fR. +In addition, names starting with a dollar sign ('$') are treated as environment variables, like regular shell escaping. +.br +Note: The brace syntax +.RI (${ varname }) +is, as of v1\&.2\&.0 not supported. + +See +.B /usr/share/doc/mpdris/sample\&.mpdris\&.conf +for an example configuration. +.SH OPTIONS +.TP +.BI addr\fR\ =\ \(dq
\fR\(dq +The IP address that MPD runs on. +While this can be a different machine than your own, this is very unlikely, +so in almost every case you can just leave it as the default value. + +Default: +.B \(dq127.0.0.1\(dq +.TP +.BI port\fR\ =\ +The TCP port that MPD listens on for its API. +.br +Can be configured in +.BR mpd\&.conf , +MPD defaults to +.BR 6600 . + +Default: +.B 6600 +.TP +.BI retries\fR\ =\ +The amount of times to retry to get a connection to MPD before exiting + +Default: +.B 3 +.TP +.BI music_directory\fR\ =\ \(dq \fR\(dq +The root directory where your music is stored and is configured in +.BR mpd\&.conf . +It is very likely that this is just +.BR ~/Music . +.br +This directory will additionally be used to search for covers; for more information, see the +.B DESCRIPTION +section in +.MR mpdris 1 . + +Default: +.B \(dq~/Music\(dq +.TP +.BI cover_directory\fR\ =\ \(dq \fR\(dq +The dedicated directory to where your covers are stored. +.br +For more information, see the +.B DESCRIPTION +section in +.MR mpdris 1 . + +Default: +.B \(dq~/Music/covers\(dq +.SH STANDARDS +Tom's Obvious, Minimal Language (TOML) +.SH BUGS +Please report any issues and bugs to +.UR https://github.com/jasger9000/mpdris/issues +.UE +.SH AUTHORS +J. Gerhards (\c +.MT g1.jasger@gmail.com +.ME ")" +& Contributors + +.UR https://github.com/jasger9000/mpdris/graphs/contributors +GitHub contributor graph +.UE +.SH SEE ALSO +.MR mpdris 1 , +.MR mpd\&.conf 5 , +.MR mpd 1 From 626f0d999da98220f52990ca16957e4622903a71 Mon Sep 17 00:00:00 2001 From: "J. Gerhards" Date: Wed, 11 Jun 2025 19:50:55 +0200 Subject: [PATCH 4/5] rewrite some of the sample config rewrite the cover_directory and music_directory sections of the config, removing the information on cover searching, and directing users to the README or man page. This is just to make me not having to write documentation for one feature three times in different formats. --- resources/sample.mpdris.conf | 26 ++++---------------------- 1 file changed, 4 insertions(+), 22 deletions(-) diff --git a/resources/sample.mpdris.conf b/resources/sample.mpdris.conf index 9fad156..ac19392 100644 --- a/resources/sample.mpdris.conf +++ b/resources/sample.mpdris.conf @@ -14,32 +14,14 @@ # The root directory where your music is stored, configured in mpd.conf # It is very likely that this is just ~/Music -# Note: while there is shell escaping, the brace syntax (${varname}) is as of v.1.2.0 not supported # -# - $music_directory/$song_path/$filename.$ext -# - $music_directory/$song_path/cover.$ext -# -# $ext can be one of the following values: jpg, jpeg, png, webp, avif, jxl, bmp, gif, heif, heic -# For an alternative cover path and more detail on covers, please read the section on cover_directory below. -# mpdris will search this directory for covers like this: +# mpdris will search this directory for song covers; +# for more information on this, please look at the README or the DESCRIPTION in mpdris(1). # # music_directory = "~/Music" -# The dedicated directory to where your covers are stored. -# mpdris will search this directory for covers like this: -# $cover_directory/$song_path/$filename.$ext -# -# $ext can be one of the following values: jpg, jpeg, png, webp, avif, jxl, bmp, gif, heif, heic -# -# Example: -# Let's say you have a user who stores their Music in ~/Music and set their cover_directory -# to be in ~/Music/Pictures/songcovers. -# If they now play the song Resurrections.mp3 located in ~/Music/Celeste, mpdris will search in -# ~/Pictures/songcovers/Celeste/ for a file named Resurrections with one of the above mentioned file extensions. +# The dedicated directory to where your song covers are stored. # -# Alternatively if the song is located in a sub-directory, you can name a cover file the same name as the directory -# and it will be used for every song in that directory. -# So sticking with the example from above, mpdris will search for a file named Celeste in cover_directory -# with one of the above listed extensions. +# For more information on covers, please look at the README or the DESCRIPTION in mpdris(1). # # cover_directory = "~/Music/covers" From f6b356a3e6d16cd2c5f9006421c1f2e910630066 Mon Sep 17 00:00:00 2001 From: "J. Gerhards" Date: Wed, 11 Jun 2025 19:56:31 +0200 Subject: [PATCH 5/5] fix a bit of grammar in the sample config and args --- resources/sample.mpdris.conf | 4 ++-- src/args.rs | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/resources/sample.mpdris.conf b/resources/sample.mpdris.conf index ac19392..391ad2c 100644 --- a/resources/sample.mpdris.conf +++ b/resources/sample.mpdris.conf @@ -1,4 +1,4 @@ -# The ip-address that MPD runs on +# The IP address that MPD runs on # While this can be a different machine than your own, this is very unlikely, # so in almost every case you can just leave it as the default value # @@ -8,7 +8,7 @@ # # port = 6600 -# The amount of times to retry to get a connection to MPD before exiting +# The number of times to retry to get a connection to MPD before exiting # # retries = 3 diff --git a/src/args.rs b/src/args.rs index b98d089..c078b3c 100644 --- a/src/args.rs +++ b/src/args.rs @@ -20,7 +20,7 @@ pub struct Args { /// number of times mpdris tries to reconnect to mpd before exiting. Set to -1 to retry infinite times #[argh(option, short = 'r')] pub retries: Option, - /// path to config file to use instead of the default + /// the path to the config file to use instead of the computed default #[argh(option, default = "get_config_path()")] pub config: PathBuf, /// the logging level to use. May be one of: trace, debug, info, warn, error @@ -29,7 +29,7 @@ pub struct Args { /// when set, will try to fork into a daemon upon launch #[argh(switch)] pub daemon: bool, - /// when set, acts as a daemon without forking the process + /// set to act as a systemd service. Acts like a daemon without forking #[argh(switch)] pub service: bool, }