From 788f65c1a15a9f28064ef684e40c79499df22524 Mon Sep 17 00:00:00 2001 From: jcorporation Date: Sun, 22 Sep 2024 20:51:48 +0200 Subject: [PATCH] Upd: layout improvements --- docs/010-installation/compiling/build-sh.md | 2 +- docs/010-installation/compiling/freebsd.md | 14 +++++----- docs/010-installation/compiling/index.md | 6 ++++- docs/010-installation/compiling/openwrt.md | 7 +++-- docs/010-installation/compiling/termux.md | 7 +++-- docs/010-installation/distributions.md | 8 +++--- docs/010-installation/docker.md | 8 +++--- .../prebuild-packages-debian.md | 1 - docs/010-installation/prebuild-packages.md | 1 - docs/020-configuration/acl.md | 7 ++--- .../020-configuration/command-line-options.md | 1 - docs/020-configuration/configuration-files.md | 16 +++++------- docs/020-configuration/index.md | 15 +++++------ docs/020-configuration/logging.md | 2 -- docs/020-configuration/mpd-connection.md | 3 --- docs/020-configuration/pin-protection.md | 3 +-- docs/020-configuration/ssl.md | 5 +--- docs/030-running.md | 14 +++++----- docs/040-debug.md | 4 +-- docs/050-scripting/functions/diskcache.md | 1 - docs/050-scripting/functions/gpio.md | 2 +- docs/050-scripting/functions/http_client.md | 2 -- docs/050-scripting/functions/http_replies.md | 2 -- docs/050-scripting/functions/index.md | 3 +-- docs/050-scripting/functions/json.md | 1 - docs/050-scripting/functions/mympd_api.md | 1 - docs/050-scripting/functions/mympd_dialog.md | 1 - docs/050-scripting/functions/mympd_init.md | 2 -- .../050-scripting/functions/system_command.md | 1 - docs/050-scripting/functions/util.md | 1 - docs/050-scripting/index.md | 1 - docs/060-references/api/index.md | 7 +++-- docs/060-references/api/methods.md | 1 - docs/060-references/api/notifications.md | 2 -- docs/060-references/components.md | 8 +++++- docs/060-references/custom-navbar-icons.md | 8 +++--- docs/060-references/feature-matrix.md | 7 ++--- docs/060-references/filesystem-hierarchy.md | 2 -- docs/060-references/index.md | 1 - docs/060-references/local-playback.md | 1 - docs/060-references/lyrics.md | 1 - docs/060-references/partitions.md | 1 - docs/060-references/pictures.md | 1 - docs/060-references/published-directories.md | 2 -- docs/060-references/smart-playlists.md | 7 +++-- docs/060-references/sticker.md | 1 - docs/060-references/tags.md | 1 - docs/060-references/translating.md | 7 ++--- docs/060-references/trigger.md | 1 - docs/060-references/webradios.md | 10 +++---- docs/060-references/webserver-uris.md | 4 +-- .../behind-a-reverse-proxy.md | 1 - docs/070-additional-topics/index.md | 1 - .../mpd-satellite-setup.md | 5 +++- .../multiple-myMPD-instances-on-same-host.md | 8 +++--- .../multiroom-audio-using-pulseaudio-rtp.md | 26 +++++++++---------- .../recommended-mpd-configuration.md | 3 +-- docs/080-known-issues.md | 1 - docs/090-security.md | 17 ++++++------ docs/_includes/.pages | 1 + docs/{000-index.md => index.md} | 1 - mkdocs.yml | 18 +++++++++++++ 62 files changed, 131 insertions(+), 166 deletions(-) create mode 100644 docs/_includes/.pages rename docs/{000-index.md => index.md} (99%) diff --git a/docs/010-installation/compiling/build-sh.md b/docs/010-installation/compiling/build-sh.md index 576c0e6c2..96091a0ea 100644 --- a/docs/010-installation/compiling/build-sh.md +++ b/docs/010-installation/compiling/build-sh.md @@ -52,7 +52,7 @@ You can self create packages for your distribution: - `./build.sh pkgdebian` for Debian based distributions (e.g. Ubuntu. Raspbian) - `./build.sh pkgrpm` for RPM based distributions (e.g. openSUSE, Fedora) - `./build.sh pkgdocker` to create a Docker image based on Alpine Linux -- For gentoo you have to create a local overlay: https://wiki.gentoo.org/wiki/Custom_repository, the ebuild file is in the directory `contrib/packaging/gentoo` +- For gentoo you have to create a [local overlay](https://wiki.gentoo.org/wiki/Custom_repository), the ebuild file is in the directory `contrib/packaging/gentoo` - Build a [OpenWrt package](openwrt.md) ### Cross compiling debian packages diff --git a/docs/010-installation/compiling/freebsd.md b/docs/010-installation/compiling/freebsd.md index 2b2d9ed15..b29a7b816 100644 --- a/docs/010-installation/compiling/freebsd.md +++ b/docs/010-installation/compiling/freebsd.md @@ -17,12 +17,12 @@ It is expected you have /usr/ports populated. 1. Copy the contents of `contrib/packaging/freebsd` to `/usr/ports` 2. Generate the checksums: - ``` + ``` sh cd /usr/ports/multimedia/mympd/ make makesum - ``` + ``` sh 3. Install myMPD: - ``` + ``` sh make install make clean ``` @@ -36,20 +36,20 @@ I would use the poudriere's ports tree installed in `/usr/local/poudriere/ports/ 1. Copy the contents of `contrib/packaging/freebsd` to `/usr/local/poudriere/ports/local` 2. Generate the checksums: - ``` + ``` sh cd /usr/local/poudriere/ports/local/multimedia/mympd make makesum ``` 3. If the previous step fails, you may need to create temporary symlink from `/usr/ports` to this local tree (revert it back afterwards): - ``` + ``` sh mv /usr/ports /usr/ports.bu ln -s /usr/local/poudriere/ports/local /usr/ports ``` 4. Build the myMPD package (consult the options with the handbook): - ``` + ``` sh poudriere bulk -j 13amd64 -p local multimedia/mympd ``` 5. Install the package. You may need to add poudriere's repository if you haven't done that earlier. - ``` + ``` sh pkg install myMPD ``` diff --git a/docs/010-installation/compiling/index.md b/docs/010-installation/compiling/index.md index 0edbb57f0..c2095de6f 100644 --- a/docs/010-installation/compiling/index.md +++ b/docs/010-installation/compiling/index.md @@ -1,5 +1,4 @@ --- - title: Compiling --- @@ -40,6 +39,11 @@ myMPD has only a few dependencies beside the standard c libraries. Not installin - flac - to extract embedded coverimages - liblua >= 5.3.0 - for myMPD scripting - libmygpio - for GPIO scripting functions +- Documentation: + - Doxygen + - JSDoc + - LuaDoc + - mkdocs You can type `./build.sh installdeps` as root to install the dependencies (works only for supported distributions). For all other distributions you must install the packages manually. diff --git a/docs/010-installation/compiling/openwrt.md b/docs/010-installation/compiling/openwrt.md index 3ba2000a4..ce4f9a158 100644 --- a/docs/010-installation/compiling/openwrt.md +++ b/docs/010-installation/compiling/openwrt.md @@ -1,5 +1,4 @@ --- - title: OpenWrt --- @@ -9,14 +8,14 @@ title: OpenWrt The SDK must match the version of OpenWrt installed on Your device. 2. Unpack SDK and change current directory to it. 3. Run following commands to download dependencies recipes: - ``` + ```sh scripts/feeds update -a scripts/feeds install libflac libid3tag liblua5.3 libopenssl libpcre2 ``` 4. Copy contents of `contrib/packaging/openwrt` from myMPD tree to `package/mympd` directory of SDK. 5. To build package run: - ``` + ```sh make -j$(nproc) BUILD_LOG=1 ``` 6. Resulting package will be placed in `bin` directory. @@ -25,7 +24,7 @@ title: OpenWrt 1. Clone the OpenWrt tree [https://git.openwrt.org/openwrt/openwrt.git](https://git.openwrt.org/openwrt/openwrt.git) 2. Run following commands to download dependencies recipes: - ``` + ```sh scripts/feeds update -a scripts/feeds install libflac libid3tag liblua5.3 libopenssl libpcre2 ``` diff --git a/docs/010-installation/compiling/termux.md b/docs/010-installation/compiling/termux.md index 35cd1ab3e..232fcc22e 100644 --- a/docs/010-installation/compiling/termux.md +++ b/docs/010-installation/compiling/termux.md @@ -1,5 +1,4 @@ --- - title: Termux --- @@ -29,7 +28,7 @@ make -C release Create the config directory for myMPD and run it to create the config files from the environment variables -``` +```sh mkdir -p $HOME/.config/mympd export MYMPD_HTTP_PORT=8080 # you can use '80' if using root @@ -46,7 +45,7 @@ $HOME/myMPD/release/bin/mympd -w $HOME/.config/mympd # run it After this run myMPD with just this, the rest is necessary for the first start only -``` +```sh $HOME/myMPD/release/bin/mympd -w $HOME/.config/mympd ``` @@ -54,7 +53,7 @@ $HOME/myMPD/release/bin/mympd -w $HOME/.config/mympd I made this little script which should run mympd as root with little trouble **(run it as the user!)** -``` +```sh #!/bin/bash su root -c "$HOME/myMPD/release/bin/mympd -w $HOME/.config/mympd -u $(whoami)" ``` diff --git a/docs/010-installation/distributions.md b/docs/010-installation/distributions.md index 5243086a1..2e4ca97a7 100644 --- a/docs/010-installation/distributions.md +++ b/docs/010-installation/distributions.md @@ -1,5 +1,4 @@ --- - title: Distributions --- @@ -15,10 +14,9 @@ myMPD is available in the following distributions: - [Snakeoil OS](https://www.snakeoil-os.net/) - [Termux](https://termux.com/) +!!! info + If you want to package myMPD for any other distribution don't hesitate to [contact me](https://github.com/jcorporation). + ## myMPDos [myMPDos](https://github.com/jcorporation/myMPDos) is my Raspberry Pi image (aarch64) based on Alpine Linux. It is running entirely in RAM and provides the latest MPD and myMPD packages and some goodies. - ---- - -If you want to package myMPD for any other distribution don't hesitate to [contact me](https://github.com/jcorporation). diff --git a/docs/010-installation/docker.md b/docs/010-installation/docker.md index 533af151f..2e3c6a9a5 100644 --- a/docs/010-installation/docker.md +++ b/docs/010-installation/docker.md @@ -1,5 +1,4 @@ --- - title: Docker --- @@ -7,8 +6,8 @@ The Docker images are based on [Alpine Linux](https://alpinelinux.org). They are There are two images: -- mympd/mympd: the latest stable release -- mympd/mympd-devel: development version +- [mympd/mympd](https://github.com/users/jcorporation/packages/container/package/mympd%2Fmympd): the latest stable release +- [mympd/mympd-devel](https://github.com/users/jcorporation/packages/container/package/mympd%2Fmympd-devel): development version Available architectures: @@ -38,14 +37,13 @@ Starts the myMPD docker container: | `/var/lib/mpd/music/` | MPD music directory. Use the same path in the container to enable auto detection. | | `/var/lib/mpd/playlists/` | MPD playlist directory. Use the same path in the container to enable auto detection. | - You must create the `cachedir` and `workdir` before starting the container. ### Docker Compose Save this as `docker-compose.yml`: -```yml +```yaml services: mympd: image: ghcr.io/jcorporation/mympd/mympd diff --git a/docs/010-installation/prebuild-packages-debian.md b/docs/010-installation/prebuild-packages-debian.md index 9308e08cc..2717a94d9 100644 --- a/docs/010-installation/prebuild-packages-debian.md +++ b/docs/010-installation/prebuild-packages-debian.md @@ -1,5 +1,4 @@ --- - title: Debian Installation --- diff --git a/docs/010-installation/prebuild-packages.md b/docs/010-installation/prebuild-packages.md index 43416274d..4c8aa283f 100644 --- a/docs/010-installation/prebuild-packages.md +++ b/docs/010-installation/prebuild-packages.md @@ -1,5 +1,4 @@ --- - title: Prebuild packages --- diff --git a/docs/020-configuration/acl.md b/docs/020-configuration/acl.md index cc1c82476..411f72dd1 100644 --- a/docs/020-configuration/acl.md +++ b/docs/020-configuration/acl.md @@ -1,5 +1,4 @@ --- - title: ACL --- @@ -9,9 +8,8 @@ The ACL is a comma separated list of IPv4 subnets: x.x.x.x/x Each subnet is prep If the acl is empty, all connections are allowed else all connections are denied if not explicitly allowed. -
-ACLs for IPv6 are currently not supported. -
+!!! info + ACLs for IPv6 are currently not supported. ## Example ACLs @@ -20,4 +18,3 @@ ACLs for IPv6 are currently not supported. | `+0.0.0.0/0`| Allow all | | `+127.0.0.0/8`| Allow localhost | | `+127.0.0.0/8,+192.168.0.0/24` | Allow localhost and all hosts in the net 192.168.0.x | - diff --git a/docs/020-configuration/command-line-options.md b/docs/020-configuration/command-line-options.md index a317d5235..523905142 100644 --- a/docs/020-configuration/command-line-options.md +++ b/docs/020-configuration/command-line-options.md @@ -17,4 +17,3 @@ The `workdir` and `cachedir` options are useful if you want to run more then one | `-w`, `--workdir ` | working directory (default: `/var/lib/mympd`). This folder must exist, if not started as root. | | `-a`, `--cachedir ` | cache directory (default: `/var/cache/mympd`). This folder must exist, if not started as root. | | `-p`, `--pin` | sets a pin for myMPD settings | - diff --git a/docs/020-configuration/configuration-files.md b/docs/020-configuration/configuration-files.md index 608c99970..d7f0f6092 100644 --- a/docs/020-configuration/configuration-files.md +++ b/docs/020-configuration/configuration-files.md @@ -5,21 +5,19 @@ title: Configuration files At the first start (if there is no config folder in the working folder) myMPD reads some environment variables and writes the configuration files. -
-After the first start all environment variables are ignored, except loglevel. -
+!!! tip + After the first start all environment variables are ignored, except loglevel. To change these settings afterwards, you can use the `mympd-config` utility and restart myMPD. As an alternative you can edit the files in the folder `/var/lib/mympd/config/`. You can use `mympd -c` to create the initial configuration in the `/var/lib/mympd/config/` directory. -**Note:** +!!! note + Use [systemd-run](../030-running.md#manual-startup), if you use a distribution with systemd, e.g.: -Use [systemd-run](../030-running.md#manual-startup), if you use a distribution with systemd, e.g.: - -```sh -systemd-run -p DynamicUser=yes -p StateDirectory=mympd -p CacheDirectory=mympd -E MYMPD_LOGLEVEL=4 -E MYMPD_HTTP=false -E MYMPD_SSL_PORT=1333 mympd -c -``` + ```sh + systemd-run -p DynamicUser=yes -p StateDirectory=mympd -p CacheDirectory=mympd -E MYMPD_LOGLEVEL=4 -E MYMPD_HTTP=false -E MYMPD_SSL_PORT=1333 mympd -c + ``` ## General options diff --git a/docs/020-configuration/index.md b/docs/020-configuration/index.md index 9e5494bc2..c30b5ac39 100644 --- a/docs/020-configuration/index.md +++ b/docs/020-configuration/index.md @@ -1,5 +1,4 @@ --- - title: Configuration --- @@ -7,16 +6,16 @@ myMPD has no single configuration file. Most of the options are configurable thr There are some command line options to define basic settings, for example the working directory. -- Command line options +- [Command line options](command-line-options.md) myMPD populates at first startup the default configuration files. You can configure this files with the `mympd-config` utility. -- Configuration files -- MPD connection +- [Configuration files](configuration-files.md) +- [MPD connection](mpd-connection.md) Other setting that are not configurable in the web-ui: -- ACL -- Logging -- SSL -- Pin protection +- [ACL](acl.md) +- [Logging](logging.md) +- [SSL](ssl.md) +- [Pin protection](pin-protection.md) diff --git a/docs/020-configuration/logging.md b/docs/020-configuration/logging.md index 22ef80c61..05bb75a09 100644 --- a/docs/020-configuration/logging.md +++ b/docs/020-configuration/logging.md @@ -1,5 +1,4 @@ --- - title: Logging --- @@ -18,5 +17,4 @@ The log levels are unix default. | 6 | info | | 7 | debug | - If you want to start myMPD with a different loglevel as configured you can set the `MYMPD_LOGLEVEL` environment variable accordingly. diff --git a/docs/020-configuration/mpd-connection.md b/docs/020-configuration/mpd-connection.md index ddaa9aa01..6ff5bf6ed 100644 --- a/docs/020-configuration/mpd-connection.md +++ b/docs/020-configuration/mpd-connection.md @@ -1,5 +1,4 @@ --- - title: MPD connection --- @@ -13,7 +12,6 @@ The mpd connection settings can be configured in the web-ui (Main menu -> MPD co | MPD port | 6600 | | MPD timeout | 30 | - ### MPD autodetection myMPD tries to autodetect the mpd connection only at first start (if no mpd_host file is found in the `state` directory). @@ -32,5 +30,4 @@ myMPD tries to autodetect the mpd connection only at first start (if no mpd_host | MPD_PORT | MPD port | | MPD_TIMEOUT | MPD timeout in seconds | - This is done after dropping privileges to the mympd user. diff --git a/docs/020-configuration/pin-protection.md b/docs/020-configuration/pin-protection.md index a42d59559..c1865ee38 100644 --- a/docs/020-configuration/pin-protection.md +++ b/docs/020-configuration/pin-protection.md @@ -1,5 +1,4 @@ --- - title: Pin protection --- @@ -13,4 +12,4 @@ You can goto the main menu and login to create a session, press `L` or simply ta The session is valid until restart of myMPD, closing the browser, refreshing the site or you logout. -The API documentation shows whether a method is protected or not. +The [API documentation](../060-references/api/methods.md) shows whether a method is protected or not. diff --git a/docs/020-configuration/ssl.md b/docs/020-configuration/ssl.md index dbbc7f893..ba3eb3b70 100644 --- a/docs/020-configuration/ssl.md +++ b/docs/020-configuration/ssl.md @@ -1,5 +1,4 @@ --- - title: SSL --- @@ -23,8 +22,7 @@ The default certificates are saved in the directory `/var/lib/mympd/ssl/`. | server.pem | Server certificate | | server.key | Server private key | - -The server certificates SAN is: +The server certificate SAN is: - DNS: localhost - DNS: ip6-localhost @@ -54,4 +52,3 @@ You can of course use your own certificate, e.g. from [Let's Encrypt](https://le | custom_cert | true | | ssl_key | path to custom ssl key | | ssl_cert | path to custom ssl certificate | - diff --git a/docs/030-running.md b/docs/030-running.md index e43afdc0a..a2b3eb561 100644 --- a/docs/030-running.md +++ b/docs/030-running.md @@ -13,7 +13,8 @@ On startup myMPD does the following: - Dropping privileges, if started as root. - Check and create the directories inside `cachedir` and `workdir`. -- **Note:** It is not supported to run myMPD as root. If started as root, myMPD drops privileges to the configured user (default mympd). +!!! note + It is not supported to run myMPD as root. If started as root, myMPD drops privileges to the configured user (default mympd). ## Startup script @@ -22,7 +23,7 @@ The installation process installs a LSB compatible startup script / systemd unit | INIT SYSTEM | SCRIPT | | ----------- | ------ | | open-rc | `/etc/init.d/mympd` | -| systemd | `/usr/lib/systemd/system/mympd` or `/lib/systemd/system/mympd` | +| systemd | `/usr/lib/systemd/system/mympd` and`/usr/lib/systemd/user/mympd` | | sysVinit | `/etc/init.d/mympd` | ### Systemd usage @@ -35,12 +36,13 @@ The default myMPD service unit uses the `DynamicUser=` directive, therefore no s **Example: add the mympd user to the music group** -``` +```sh mkdir /etc/systemd/system/mympd.service.d echo -e '[Service]\nSupplementaryGroups=music' > /etc/systemd/system/mympd.service.d/music-group.conf ``` -- **Note:** The default systemd service unit supports only systemd v235 and above. +!!! note + The default systemd service unit supports only systemd v235 and above. ### Openrc usage @@ -50,11 +52,11 @@ myMPD logs to syslog to facility `daemon`, you can see the live logs with `tail ## Manual startup -To start myMPD in the actual console session: `mympd` (myMPD keeps in foreground and logs to the console, press CTRL+C to stop myMPD) +To start myMPD in the actual console session: `mympd` (myMPD keeps in foreground and logs to the console, press `CTRL+C` to stop myMPD) If you use a distribution with systemd (without a static mympd user): -``` +```sh systemd-run -t -p DynamicUser=yes -p StateDirectory=mympd -p CacheDirectory=mympd /usr/bin/mympd ``` diff --git a/docs/040-debug.md b/docs/040-debug.md index bd5139dfd..2e4b69e2c 100644 --- a/docs/040-debug.md +++ b/docs/040-debug.md @@ -1,5 +1,4 @@ --- - title: Debug --- @@ -16,7 +15,8 @@ Tips to debug problems with myMPD. Try these steps and reproduce the error. - Press Ctrl + C to abort - Reset loglevel: `unset MYMPD_LOGLEVEL` -- **Note:** Use [systemd-run](030-running.md#manual-startup), if you use a distribution with systemd +!!! note + Use [systemd-run](030-running.md#manual-startup), if you use a distribution with systemd ### Get logs from running myMPD diff --git a/docs/050-scripting/functions/diskcache.md b/docs/050-scripting/functions/diskcache.md index 4b08e8306..d7c27bc7e 100644 --- a/docs/050-scripting/functions/diskcache.md +++ b/docs/050-scripting/functions/diskcache.md @@ -1,5 +1,4 @@ --- - title: Disk caches --- diff --git a/docs/050-scripting/functions/gpio.md b/docs/050-scripting/functions/gpio.md index 12feb59c8..eea862046 100644 --- a/docs/050-scripting/functions/gpio.md +++ b/docs/050-scripting/functions/gpio.md @@ -1,4 +1,4 @@ - +--- title: GPIO --- diff --git a/docs/050-scripting/functions/http_client.md b/docs/050-scripting/functions/http_client.md index d5fe7113e..6a349ea7f 100644 --- a/docs/050-scripting/functions/http_client.md +++ b/docs/050-scripting/functions/http_client.md @@ -1,5 +1,4 @@ --- - title: HTTP client --- @@ -61,4 +60,3 @@ end | rc | integer | 0 = success, 1 = error | | code | integer | http response code, e.g. 200 | | headers | table | http headers | - diff --git a/docs/050-scripting/functions/http_replies.md b/docs/050-scripting/functions/http_replies.md index 314839d29..a54629f99 100644 --- a/docs/050-scripting/functions/http_replies.md +++ b/docs/050-scripting/functions/http_replies.md @@ -1,5 +1,4 @@ --- - title: HTTP Replies --- @@ -64,4 +63,3 @@ return mympd.http_jsonrpc_warn(method, msg) | --------- | ---- | ----------- | | method | integer | myMPD API method | | msg | string | Error message | - diff --git a/docs/050-scripting/functions/index.md b/docs/050-scripting/functions/index.md index eed275bd6..5216464a1 100644 --- a/docs/050-scripting/functions/index.md +++ b/docs/050-scripting/functions/index.md @@ -1,5 +1,4 @@ --- - title: Functions --- @@ -40,4 +39,4 @@ List of myMPD specific Lua functions. | [mympd.urldecode](util.md) | Decodes a URL encoded string. | | [mympd.urlencode](util.md) | URL encodes a string. | -- [LuaDoc](../../luadoc/files/debug/contrib/lualibs/mympd.html) +- [LuaDoc](../../luadoc/files/release/contrib/lualibs/mympd.html) diff --git a/docs/050-scripting/functions/json.md b/docs/050-scripting/functions/json.md index bb3fa7849..fdd62f5df 100644 --- a/docs/050-scripting/functions/json.md +++ b/docs/050-scripting/functions/json.md @@ -1,5 +1,4 @@ --- - title: Json --- diff --git a/docs/050-scripting/functions/mympd_api.md b/docs/050-scripting/functions/mympd_api.md index 5056b65e9..1d20809f2 100644 --- a/docs/050-scripting/functions/mympd_api.md +++ b/docs/050-scripting/functions/mympd_api.md @@ -1,5 +1,4 @@ --- - title: Accessing the myMPD API --- diff --git a/docs/050-scripting/functions/mympd_dialog.md b/docs/050-scripting/functions/mympd_dialog.md index d57c6c68d..29088089c 100644 --- a/docs/050-scripting/functions/mympd_dialog.md +++ b/docs/050-scripting/functions/mympd_dialog.md @@ -1,5 +1,4 @@ --- - title: Accessing the myMPD API --- diff --git a/docs/050-scripting/functions/mympd_init.md b/docs/050-scripting/functions/mympd_init.md index 251b98013..62f811737 100644 --- a/docs/050-scripting/functions/mympd_init.md +++ b/docs/050-scripting/functions/mympd_init.md @@ -1,5 +1,4 @@ --- - title: Accessing myMPD and MPD status information --- @@ -68,4 +67,3 @@ The lua table mympd_state is populated with following fields. | `uri` | String | Song uri | | `Duration` | Integer | Song duration in seconds | | Tag | Tag value(s) | MPD tag name with values. | - diff --git a/docs/050-scripting/functions/system_command.md b/docs/050-scripting/functions/system_command.md index 914fda7ce..988fd17ed 100644 --- a/docs/050-scripting/functions/system_command.md +++ b/docs/050-scripting/functions/system_command.md @@ -1,5 +1,4 @@ --- - title: Execute a system command --- diff --git a/docs/050-scripting/functions/util.md b/docs/050-scripting/functions/util.md index f249e0759..3d36be03c 100644 --- a/docs/050-scripting/functions/util.md +++ b/docs/050-scripting/functions/util.md @@ -1,5 +1,4 @@ --- - title: Utility Functions --- diff --git a/docs/050-scripting/index.md b/docs/050-scripting/index.md index 679d99def..6409e7ffa 100644 --- a/docs/050-scripting/index.md +++ b/docs/050-scripting/index.md @@ -1,5 +1,4 @@ --- - title: Scripting --- diff --git a/docs/060-references/api/index.md b/docs/060-references/api/index.md index 4ff9bb884..22586f6f5 100644 --- a/docs/060-references/api/index.md +++ b/docs/060-references/api/index.md @@ -1,5 +1,4 @@ --- - title: API Documentation --- @@ -28,11 +27,11 @@ Notifications from the backend to the frontend are sent over a websocket connect ## Example API calls -``` +``` json {"jsonrpc":"2.0","id":0,"method":"MYMPD_API_PLAYER_STATE","params":{}} ``` -``` +``` json {"jsonrpc":"2.0","id":0,"method":"MYMPD_API_PLAYER_VOLUME_SET","params":{"volume":60}} ``` @@ -42,7 +41,7 @@ If myMPD is protected with a pin some methods require authentication with a spec ### Authenticate -``` +``` json {"jsonrpc":"2.0","id":0,"method":"MYMPD_API_SESSION_LOGIN","params":{"pin": ""}} ``` diff --git a/docs/060-references/api/methods.md b/docs/060-references/api/methods.md index 0fba2f2de..778a7c5a3 100644 --- a/docs/060-references/api/methods.md +++ b/docs/060-references/api/methods.md @@ -1,5 +1,4 @@ --- - title: API Methods --- diff --git a/docs/060-references/api/notifications.md b/docs/060-references/api/notifications.md index aeb97410e..e68fa38f0 100644 --- a/docs/060-references/api/notifications.md +++ b/docs/060-references/api/notifications.md @@ -1,5 +1,4 @@ --- - title: Websocket Notifications --- @@ -36,4 +35,3 @@ The websocket endpoint accepts following messages: | ------- | -------- | ----------- | | ping | pong | Keepalive | | id:`` | ok | Used to send the jsonrpc Client ID generated for this session | - diff --git a/docs/060-references/components.md b/docs/060-references/components.md index 1aac4818a..fced89ccb 100644 --- a/docs/060-references/components.md +++ b/docs/060-references/components.md @@ -1,5 +1,4 @@ --- - title: Components --- @@ -23,3 +22,10 @@ myMPD is opensource and build on top off other great opensource software. - [sds](https://github.com/jcorporation/sds) (dynamic string handling) - [utest](https://github.com/sheredom/utest.h) (unit tests) - [utf8](https://github.com/sheredom/utf8.h) (utf8 handling) + +## Documentation + +- [Doxygen](https://www.doxygen.nl/index.html) +- [JSDoc](https://jsdoc.app/) +- [LuaDoc](https://keplerproject.github.io/luadoc/) +- [mkdocs](https://www.mkdocs.org/) diff --git a/docs/060-references/custom-navbar-icons.md b/docs/060-references/custom-navbar-icons.md index 077b47bce..3726032ec 100644 --- a/docs/060-references/custom-navbar-icons.md +++ b/docs/060-references/custom-navbar-icons.md @@ -1,5 +1,4 @@ --- - title: Custom navbar icons --- @@ -13,7 +12,7 @@ The navbar icons can be customized. You must edit the file `/var/lib/mympd/state Default navbar definition: -``` +```json [ { "ligature": "home", @@ -43,10 +42,11 @@ Default navbar definition: ] ``` -### Other Example: +### Other Example URI: /Browse/Filesystem!0/-/-/-/ -``` + +```json { "ligature": "library_music", "title":"Browse", diff --git a/docs/060-references/feature-matrix.md b/docs/060-references/feature-matrix.md index 10b23c5a6..4871240ff 100644 --- a/docs/060-references/feature-matrix.md +++ b/docs/060-references/feature-matrix.md @@ -1,13 +1,11 @@ --- - title: Feature matrix --- Certain myMPD features are only available with new MPD versions. To use all myMPD functions you should use the latest stable MPD version. -
-myMPD support only MPD 0.21.0 and above. -
+!!! note + myMPD support only MPD 0.21.0 and above. | MYMPD FEATURE | MPD VERSION | DESCRIPTION | | ------------- | ----------- | ----------- | @@ -22,4 +20,3 @@ myMPD support only MPD 0.21.0 and above. | Remove range in playlist (range arg for playlistdelete) | 0.23.3 | Removes a range of songs in a playlist | | Partitions | 0.22.0 | Concurrent partition support | | Embedded albumart (readpicture) | 0.22.0 | myMPD can read pictures tags directly if it has access to the musicdirectory | - diff --git a/docs/060-references/filesystem-hierarchy.md b/docs/060-references/filesystem-hierarchy.md index 80e5d184f..e059d904f 100644 --- a/docs/060-references/filesystem-hierarchy.md +++ b/docs/060-references/filesystem-hierarchy.md @@ -1,5 +1,4 @@ --- - title: Filesystem hierarchy --- @@ -31,4 +30,3 @@ myMPD uses GNU standard installation directories. | /var/lib/mympd/state/ | Global state files | | /var/lib/mympd/state/`` | Partition specific state files | | /var/lib/mympd/tags/ | Directory for caches | - diff --git a/docs/060-references/index.md b/docs/060-references/index.md index 20b106b28..53c984627 100644 --- a/docs/060-references/index.md +++ b/docs/060-references/index.md @@ -1,5 +1,4 @@ --- - title: References --- diff --git a/docs/060-references/local-playback.md b/docs/060-references/local-playback.md index 23968fc8d..dbd1f845c 100644 --- a/docs/060-references/local-playback.md +++ b/docs/060-references/local-playback.md @@ -1,5 +1,4 @@ --- - title: Local playback --- diff --git a/docs/060-references/lyrics.md b/docs/060-references/lyrics.md index 72c493be5..2bf84b48f 100644 --- a/docs/060-references/lyrics.md +++ b/docs/060-references/lyrics.md @@ -1,5 +1,4 @@ --- - title: Lyrics --- diff --git a/docs/060-references/partitions.md b/docs/060-references/partitions.md index 78ce11396..0ffa62700 100644 --- a/docs/060-references/partitions.md +++ b/docs/060-references/partitions.md @@ -1,5 +1,4 @@ --- - title: Partitions --- diff --git a/docs/060-references/pictures.md b/docs/060-references/pictures.md index 7e81b3ab1..bc7960804 100644 --- a/docs/060-references/pictures.md +++ b/docs/060-references/pictures.md @@ -1,5 +1,4 @@ --- - title: Pictures --- diff --git a/docs/060-references/published-directories.md b/docs/060-references/published-directories.md index 29a872b53..e0c279ef5 100644 --- a/docs/060-references/published-directories.md +++ b/docs/060-references/published-directories.md @@ -1,5 +1,4 @@ --- - title: Published directories --- @@ -12,4 +11,3 @@ myMPD publishes mpd and myMPD directories via the embedded webserver. | /browse/smartplaylists | `/var/lib/mympd/smartpls` | smart playlists | | /browse/pics | `/var/lib/mympd/pics` | myMPD pictures (pictures from here are accessible through the picture selects) | | /browse/webradios | `/var/lib/mympd/webradios` | webradio favorites m3u files | - diff --git a/docs/060-references/smart-playlists.md b/docs/060-references/smart-playlists.md index e104ea574..428e5624d 100644 --- a/docs/060-references/smart-playlists.md +++ b/docs/060-references/smart-playlists.md @@ -1,5 +1,4 @@ --- - title: Smart playlists --- @@ -28,18 +27,18 @@ Smart playlists are saved in the folder `/var/lib/mympd/smartpls` (one JSON file ### Sticker based -``` +``` json {"type": "sticker", "sticker": "like", "value": "2", "op": "=" "sort": "", "sortdesc": false, "maxentries": 200} ``` ### Newest songs -``` +``` json {"type": "newest", "timerange": 604800, "sort":"", "sortdesc": false, "maxentries": 0} ``` ### Saved search -``` +``` json {"type":"search", "expression":"((Artist contains 'test'))", "sort":"Album", "sortdesc": false, "maxentries": 0} ``` diff --git a/docs/060-references/sticker.md b/docs/060-references/sticker.md index 7b0b40180..de13a2d32 100644 --- a/docs/060-references/sticker.md +++ b/docs/060-references/sticker.md @@ -1,5 +1,4 @@ --- - title: Sticker --- diff --git a/docs/060-references/tags.md b/docs/060-references/tags.md index e7a119fb0..61e940459 100644 --- a/docs/060-references/tags.md +++ b/docs/060-references/tags.md @@ -1,5 +1,4 @@ --- - title: Tags --- diff --git a/docs/060-references/translating.md b/docs/060-references/translating.md index ed5c8d00a..6ef092e76 100644 --- a/docs/060-references/translating.md +++ b/docs/060-references/translating.md @@ -1,5 +1,4 @@ --- - title: Translating --- @@ -22,7 +21,8 @@ The translation files are imported to a public POEditor project. You can [join t [GitHub discussion](https://github.com/jcorporation/myMPD/discussions/803) -**Note:** There are some phrases that are only shortcuts for the full text. You can lookup the english phrase [here](https://github.com/jcorporation/myMPD/blob/master/src/i18n/json/en-US.json). +!!! note + There are some phrases that are only shortcuts for the full text. You can lookup the english phrase [here](https://github.com/jcorporation/myMPD/blob/master/src/i18n/json/en-US.json). ## Translation files @@ -63,7 +63,7 @@ This example is for the german translation (de-DE). You can check the translation files manually. The build process shows all missing or obsolete translations. -``` +```sh ./build.sh translate ``` @@ -72,6 +72,7 @@ Debug builds should use the new translation after a successful build. **To include it in a release build** Add it to: + - `src/web_server/embedded_files.c` - the struct `embedded_files` in `src/web_server/utility.c` - `CMakeLists.txt` diff --git a/docs/060-references/trigger.md b/docs/060-references/trigger.md index a4a1d3943..f3a7d74fa 100644 --- a/docs/060-references/trigger.md +++ b/docs/060-references/trigger.md @@ -1,5 +1,4 @@ --- - title: Trigger --- diff --git a/docs/060-references/webradios.md b/docs/060-references/webradios.md index eb2594916..9931348d9 100644 --- a/docs/060-references/webradios.md +++ b/docs/060-references/webradios.md @@ -1,20 +1,16 @@ --- - title: Webradios --- ## Online search -myMPD uses two online sources for webradios. +myMPD uses my community driven and currated [WebradioDB](https://jcorporation.github.io/webradiodb/) project. -1. [webradiodb](https://jcorporation.github.io/webradiodb/) - my project for a curated webradio database -2. [radio-browser.info](https://www.radio-browser.info/) +You can use a script to query the more popular [RadioBrowser Project](https://www.radio-browser.info/). ## Favorites -myMPD saves webradio favorites as single extended m3u files in the directory `/var/lib/mympd/webradios`. The filename is the sanitized stream uri. - -MPD loads this playlist with the curl plugin, myMPD calculates the correct http uri. If you run myMPD behind a reverse proxy, you can set the correct url with the `mympd_uri` configuration option. +MPD loads this webradio favorites with the curl plugin, myMPD calculates the correct http uri. If you run myMPD behind a reverse proxy, you can set the correct url with the `mympd_uri` configuration option. ### File format diff --git a/docs/060-references/webserver-uris.md b/docs/060-references/webserver-uris.md index 16588bdf7..e365d80af 100644 --- a/docs/060-references/webserver-uris.md +++ b/docs/060-references/webserver-uris.md @@ -1,6 +1,5 @@ --- - -title: Webserver uris +title: Webserver URIs --- Reference of all webserver uris. @@ -25,4 +24,3 @@ Reference of all webserver uris. | `/tagart?tag=&value=` | Returns the tagart thumbnail. | | `/webradio?uri=` | Webradio endpoint | | `/ws/` | Websocket endpoint | - diff --git a/docs/070-additional-topics/behind-a-reverse-proxy.md b/docs/070-additional-topics/behind-a-reverse-proxy.md index 50f0ba409..060b57597 100644 --- a/docs/070-additional-topics/behind-a-reverse-proxy.md +++ b/docs/070-additional-topics/behind-a-reverse-proxy.md @@ -1,5 +1,4 @@ --- - title: Behind a reverse proxy --- diff --git a/docs/070-additional-topics/index.md b/docs/070-additional-topics/index.md index db107a2f4..96f580d7f 100644 --- a/docs/070-additional-topics/index.md +++ b/docs/070-additional-topics/index.md @@ -1,5 +1,4 @@ --- - title: Additional topics --- diff --git a/docs/070-additional-topics/mpd-satellite-setup.md b/docs/070-additional-topics/mpd-satellite-setup.md index a621274df..9fb95940b 100644 --- a/docs/070-additional-topics/mpd-satellite-setup.md +++ b/docs/070-additional-topics/mpd-satellite-setup.md @@ -1,5 +1,4 @@ --- - title: MPD satellite setup --- @@ -39,6 +38,7 @@ Setting up the central server involves following steps: ### Configure MPD **/etc/mpd.conf** + ``` music_directory "/srv/mpd/music" playlist_directory "/srv/mpd/playlists" @@ -56,6 +56,7 @@ bind_to_address "0.0.0.0" We use NFS, but CIFS is also possible. **/etc/exports** + ``` /srv/mpd *(ro,sync,no_subtree_check) ``` @@ -79,6 +80,7 @@ Setting up the satellite involves following steps: We mount the exported directories at the os level. myMPD requires access to the music directory also. Ths music directory path should be the same on the central server and on the satellite. **/etc/fstab** + ``` central.lan:/srv/mpd /srv/mpd nfs soft,_netdev 0 0 ``` @@ -86,6 +88,7 @@ central.lan:/srv/mpd /srv/mpd nfs soft,_netdev 0 0 ### 2. Configure MPD **/etc/mpd.conf** + ``` music_directory "/srv/mpd/music" playlist_directory "/srv/mpd/playlists" diff --git a/docs/070-additional-topics/multiple-myMPD-instances-on-same-host.md b/docs/070-additional-topics/multiple-myMPD-instances-on-same-host.md index e35ff9549..374431113 100644 --- a/docs/070-additional-topics/multiple-myMPD-instances-on-same-host.md +++ b/docs/070-additional-topics/multiple-myMPD-instances-on-same-host.md @@ -1,11 +1,11 @@ --- - title: Multiple myMPD instances on same host --- You can run multiple myMPD instances on the same host connecting to different MPD instances. You must define for each myMPD instance: + - different working directory - different cache directory - different ports to listen on @@ -14,11 +14,12 @@ You must define for each myMPD instance: If the working directory is not present, you can create it: First myMPD instance: + - connect to mpd listening on socket `/run/mpd1/socket` - myMPD will listen on port 8001 - myMPD will not use ssl -``` +```sh export MPD_HOST=/run/mpd1/socket export MYMPD_HTTP_PORT=8001 export MYMPD_SSL=false @@ -26,11 +27,12 @@ mympd -w /var/lib/mympd1 -a /var/cache/mympd1 ``` Second myMPD instance: + - connect to mpd listening on socket `/run/mpd2/socket` - myMPD will listen on port 8002 for http - myMPD will listen on port 4432 for ssl traffic -``` +```sh export MPD_HOST=/run/mpd2/socket export MYMPD_HTTP_PORT=8002 export MYMPD_SSL_PORT=4432 diff --git a/docs/070-additional-topics/multiroom-audio-using-pulseaudio-rtp.md b/docs/070-additional-topics/multiroom-audio-using-pulseaudio-rtp.md index 1a29e830b..2f65fec9d 100644 --- a/docs/070-additional-topics/multiroom-audio-using-pulseaudio-rtp.md +++ b/docs/070-additional-topics/multiroom-audio-using-pulseaudio-rtp.md @@ -1,5 +1,4 @@ --- - title: Multiroom audio system using MPD/myMPD and pulseaudio --- @@ -56,13 +55,13 @@ MPD and myMPD will only run on the NAS. #### Install PulseAudio (if not already installed) -``` +```sh apt install pulseaudio,pulseaudio-utils,pulsemixer ``` #### Have Pulse audio start as system service with the following pulseaudio systemd unit file -``` +```sh # cat < /lib/systemd/system/pulseaudio.service [Unit] Description=PulseAudio Daemon @@ -100,7 +99,7 @@ pulse-access:x:111:root #### Allow MPD to output to PulseAudio -``` +```sh # usermod -a -G pulse-access mpd ## Verify @@ -114,13 +113,13 @@ pulse-access:x:111:root,mpd Notice that a distinct sink is configured for each destination device, plus another one for synchronised multiroom audio. -``` +```sh # cat <> /etc/pulse/system.pa .include /etc/pulse/rtp_server.pa EOF ``` -``` +```sh # cat < /etc/pulse/rtp_server.pa load-module module-null-sink sink_name=rtp format=s32be channels=2 rate=48000 sink_properties="device.description='MPD RTP Multicast Sink'" load-module module-rtp-send source=rtp.monitor destination_ip=239.0.0.100 @@ -142,7 +141,7 @@ EOF #### Configure MPD to send audio output to the different possible RTP sinks -``` +```sh # cat /etc/mpd.conf # Only the Audio Output part from mpd.conf is shown here @@ -199,7 +198,7 @@ No need to install mpd/mympd; only pulseaudio is required. #### Configure PulseAudio to receive audio over the Network by RTP (RealTime Transport Protocol) -``` +```sh # cat <> /etc/pulse/system.pa .include /etc/pulse/rtp.pa EOF @@ -207,7 +206,7 @@ EOF ##### Specific config file in Multimedia Room Embedded device -``` +```sh # cat << EOF > /etc/pulse/rtp.pa ### Load the RTP receiver module load-module module-rtp-recv sap_address=239.0.0.100 @@ -216,7 +215,7 @@ load-module module-rtp-recv sap_address=192.168.0.11 ##### Specific config file in Saloon Embedded device -``` +```sh # cat << EOF > /etc/pulse/rtp.pa ### Load the RTP receiver module load-module module-rtp-recv sap_address=239.0.0.100 @@ -225,7 +224,7 @@ load-module module-rtp-recv sap_address=192.168.0.12 ##### Specific config file in Attic Embedded device -``` +```sh # cat << EOF > /etc/pulse/rtp.pa ### Load the RTP receiver module load-module module-rtp-recv sap_address=239.0.0.100 @@ -234,7 +233,7 @@ load-module module-rtp-recv sap_address=192.168.0.13 ##### Specific config file in Bathroom Embedded device -``` +```sh # cat << EOF > /etc/pulse/rtp.pa ### Load the RTP receiver module load-module module-rtp-recv sap_address=239.0.0.100 @@ -245,10 +244,9 @@ load-module module-rtp-recv sap_address=192.168.0.14 The service must be started. -On the NAS, the On the receivers, the incoming RTP flows (unicast and multicast) should appear under the audio interface that's outputting them. -``` +```sh # systemctl restart pulseaudio # systemctl status pulseaudio diff --git a/docs/070-additional-topics/recommended-mpd-configuration.md b/docs/070-additional-topics/recommended-mpd-configuration.md index bbf36de50..98159b673 100644 --- a/docs/070-additional-topics/recommended-mpd-configuration.md +++ b/docs/070-additional-topics/recommended-mpd-configuration.md @@ -1,5 +1,4 @@ --- - title: Recommended MPD configuration --- @@ -13,7 +12,7 @@ sticker_file "/var/lib/mpd/sticker.sql" playlist_directory "/var/lib/mpd/playlists" # Enable metadata. If set to none, you can only browse the filesystem -metadata_to_use "AlbumArtist,Artist,Album,Title,Track,Disc,Genre,Name" +metadata_to_use "AlbumArtist,Artist,Album,Title,Track,Disc,Genre,Name,Date" # Enable also the musicbrainz_* tags if you want integration with MusicBrainz and ListenBrainz # musicbrainz_albumid is the fallback for musicbrainz_releasegroupid (MPD 0.24) #metadata_to_use "AlbumArtist,Artist,Album,Title,Track,Disc,Genre,Name,musicbrainz_artistid, musicbrainz_albumid, musicbrainz_albumartistid, musicbrainz_trackid, musicbrainz_releasetrackid" diff --git a/docs/080-known-issues.md b/docs/080-known-issues.md index 9a146f8df..8cc984bff 100644 --- a/docs/080-known-issues.md +++ b/docs/080-known-issues.md @@ -1,5 +1,4 @@ --- - title: Known issues --- diff --git a/docs/090-security.md b/docs/090-security.md index ecfe02153..0c619af5d 100644 --- a/docs/090-security.md +++ b/docs/090-security.md @@ -1,5 +1,4 @@ --- - title: Security --- @@ -25,14 +24,14 @@ If you want to access myMPD from the internet, you should add a reverse proxy wi Nevertheless myMPD is designed with security in mind. -- All input data is validated and size limited (tested with a fuzzer) -- The webserver limits the number of connections and request sizes -- The C backend is compiled with hardening flags and is regularly checked with static code analyzers -- The debug and development builds are linked with libasan to detect memory errors -- myMPD uses a fork of [Simple Dynamic Strings](https://github.com/jcorporation/sds) to prevent buffer-overflows -- Files are served with a strict [Content Security](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) and [Trusted Types](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API) Policy to prevent XSS attacks -- The javascript frontend avoids parsing of strings to dom nodes -- All included dependencies are updated regularly +- All input data is validated and size limited (tested with a fuzzer). +- The webserver limits the number of connections and request sizes. +- The C backend is compiled with hardening flags and is regularly checked with static code analyzers. +- The debug and development builds are linked with libasan to detect memory errors. +- myMPD uses a fork of [Simple Dynamic Strings](https://github.com/jcorporation/sds) to avoid error prone c string handling functions. +- Files are served with a strict [Content Security](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) and [Trusted Types](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API) Policy to prevent XSS attacks. +- The javascript frontend avoids parsing of strings to dom nodes. +- All included dependencies are updated regularly. ## Reporting diff --git a/docs/_includes/.pages b/docs/_includes/.pages new file mode 100644 index 000000000..e2d5ae912 --- /dev/null +++ b/docs/_includes/.pages @@ -0,0 +1 @@ +hide: true diff --git a/docs/000-index.md b/docs/index.md similarity index 99% rename from docs/000-index.md rename to docs/index.md index 0dd27c5c5..3b2491458 100644 --- a/docs/000-index.md +++ b/docs/index.md @@ -1,5 +1,4 @@ --- - title: myMPD Documentation --- diff --git a/mkdocs.yml b/mkdocs.yml index 670d3dc79..004848a66 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,6 +5,7 @@ theme: features: - navigation.instant - navigation.tracking + - content.code.copy font: false logo: assets/mympd-logo.svg favicon: assets/favicon.ico @@ -23,3 +24,20 @@ plugins: collapse_single_pages: true - include-markdown - search +markdown_extensions: + - tables + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + - admonition + - pymdownx.details + - pymdownx.superfences + - pymdownx.critic + - pymdownx.caret + - pymdownx.keys + - pymdownx.mark + - pymdownx.tilde