Merge pull request #528 from TheCaptain989/lidarr-flac2mp3

Lidarr: flac2mp3 Release 2.2

Author: aptalca

.assets/lidarr-synology-2.png

@@ -1,5 +1,5 @@
 # About
-A [Docker Mod](https://github.com/linuxserver/docker-mods) for the LinuxServer.io Lidarr Docker container that uses ffmpeg and a script to automatically convert downloaded FLAC files to MP3s.  Default output quality is 320Kbps constant bit rate.
+A [Docker Mod](https://github.com/linuxserver/docker-mods) for the LinuxServer.io Lidarr Docker container that uses ffmpeg and a script to automatically convert downloaded FLAC (or other format) files to MP3s.  Default output quality is 320Kbps constant bit rate.
 Advanced options act as a light wrapper to ffmpeg, allowing conversion to any supported audio format, including AAC, AC3, Opus, and many others.
 A [Batch Mode](./README.md#batch-mode) is also supported that allows usage outside of Lidarr.
 
@@ -17,7 +17,7 @@ Production Container info: ![Docker Image Size](https://img.shields.io/docker/im
 2. Configure the Docker container with all the port, volume, and environment settings from the *original container documentation* here:  
   **[linuxserver/lidarr](https://hub.docker.com/r/linuxserver/lidarr "Docker container")**
    1. Add a **DOCKER_MODS** environment variable to the `docker run` command, as follows:  
-      - Dev/test release: `-e DOCKER_MODS=thecaptain989/lidarr-flac2mp3:latest`  
+      - Dev/test release: `-e DOCKER_MODS=thecaptain989/lidarr-flac2mp3:latest`
       - Stable release: `-e DOCKER_MODS=linuxserver/mods:lidarr-flac2mp3`
 
       *Example Docker CLI Configuration*  
@@ -49,25 +49,24 @@ Production Container info: ![Docker Image Size](https://img.shields.io/docker/im
 
    This will use the defaults to create a 320Kbps MP3 file.
 
-   *For any other setting, you **must** either use one of the [included wrapper scripts](./README.md#included-wrapper-scripts) or create a custom script with the command line options you desire.  See the [Syntax](./README.md#syntax) section below.*
+   *For any other setting, you **must** use one of the supported methods to pass arguments to the script.  See the [Syntax](./README.md#syntax) section below.*
 
 ## Usage
-New file(s) with will be placed in the same directory as the original FLAC file(s) (unless redirected with the `--output` option below) and have the same owner and permissions. Existing files with the same track name will be overwritten.
+New file(s) will be placed in the same directory as the original FLAC file(s) (unless redirected with the `--output` option below) and have the same owner and permissions. Existing files with the same track name will be overwritten.
 
 By default, if you've configured Lidarr's **Recycle Bin** path correctly, the original audio file will be moved there.  
-![danger] **NOTE:** If you have *not* configured the Recycle Bin, the original FLAC audio file(s) will be deleted and permanently lost.  This behavior may be modifed with the `--keep-file` option.
+![danger] **NOTE:** If you have *not* configured the Recycle Bin, the original FLAC audio file(s) will be deleted and permanently lost.  This behavior may be modified with the `--keep-file` option.
 
 ### Syntax
->**Note:** The **Arguments** field for Custom Scripts was removed in Lidarr release [v0.7.0.1347](https://github.com/lidarr/Lidarr/commit/b9d240924f8965ebb2c5e307e36b810ae076101e "Lidarr commit notes") due to security concerns.
-To support options with this version and later, a wrapper script can be manually created that will call *flac2mp3.sh* with the required arguments.
+>**Note:** The _Arguments_ field for Custom Scripts was removed in Lidarr release [v0.7.0.1347](https://github.com/lidarr/Lidarr/commit/b9d240924f8965ebb2c5e307e36b810ae076101e "Lidarr commit notes") due to security concerns.
+
+To supply arguments to the script, you **must** either use one of the **[included wrapper scripts](./README.md#included-wrapper-scripts)**, create a **[custom wrapper script](./README.md#example-wrapper-script)**, or set the `FLAC2MP3_ARGS` **[environment variable](./README.md#environment-variable)**.
 
 #### Command Line Options and Arguments
 The script may be called with optional command line arguments.
 
 The syntax for the command line is:  
-`flac2mp3 [OPTIONS] [{-b|--bitrate} <bitrate> | {-v|--quality} <quality> | {-a|--advanced} "<options>" {-e|--extension} <extension>]`  
-OR  
-`flac2mp3 [OPTIONS] {-f|--file} <audio_file>`
+`flac2mp3 [{-d|--debug} [<level>]] [{-b|--bitrate} <bitrate> | {-v|--quality} <quality> | {-a|--advanced} "<options>" {-e|--extension} <extension>] [{-f|--file} <audio_file>] [{-k|--keepfile}] [{-o|--output} <directory>] [{-r|--regex} '<regex>'] [{-t|--tags} <taglist>]`  
 
 Where:
 
@@ -76,11 +75,13 @@ Option|Argument|Description
 -d, --debug|\[\<level\>\]|Enables debug logging. Level is optional.<br/>Default of 1 (low).<br/>2 includes API and FFmpeg output.
 -b, --bitrate|\<bitrate\>|Sets the output quality in constant bits per second (CBR).<br/>Examples: 160k, 240k, 300000<br/>**Note:** May not be specified with `-v`, `-a`, or `-e`.
 -v, --quality|\<quality\>|Sets the output variable bit rate (VBR).<br/>Specify a value between 0 and 9, with 0 being the highest quality.<br/>See the [FFmpeg MP3 Encoding Guide](https://trac.ffmpeg.org/wiki/Encode/MP3) for more details.<br/>**Note:** May not be specified with `-b`, `-a`, or `-e`.
--a, --advanced|\"\<options\>\"|Advanced ffmpeg options.<br/>The specified `options` replace all script defaults and are sent directly to ffmpeg.<br/>The `options` value must be enclosed in quotes.<br/>See [FFmpeg Options](https://ffmpeg.org/ffmpeg.html#Options) for details on valid options, and [Guidelines for high quality audio encoding](https://trac.ffmpeg.org/wiki/Encode/HighQualityAudio) for suggested usage.<br/>**Note:** Requires the `-e` option to also be specified. May not be specified with `-v` or `-b`.<br/>![danger] **WARNING:** You must specify an audio codec (by including a `-c:a <codec>` ffmpeg option) or the resulting file will contain no audio!<br/>![danger] **WARNING:** Invalid `options` could result in script failure!
--e, --extension|\<extension\>|Sets the output file extension<br/>The extension may be prefixed by a dot (".") or not.<br/>**Note:** Requires the `-a` option to also be specified. May not be specified with `-v` or `-b`.
--f, --file|<audio_file>|If included, the script enters **[Batch Mode](./README.md#batch-mode)** and converts the specified audio file.<br/>![danger] **WARNING:** Do not use this argument when called from Lidarr!
+-a, --advanced|\"\<options\>\"|Advanced ffmpeg options.<br/>The specified `options` replace all script defaults and are sent directly to ffmpeg.<br/>The `options` value must be enclosed in quotes.<br/>See [FFmpeg Options](https://ffmpeg.org/ffmpeg.html#Options) for details on valid options, and [Guidelines for high quality audio encoding](https://trac.ffmpeg.org/wiki/Encode/HighQualityAudio) for suggested usage.<br/>**Note:** Requires the `-e` option to also be specified. May not be specified with `-v` or `-b`.<br/>![warning] **WARNING:** You must specify an audio codec (by including a `-c:a <codec>` ffmpeg option) or the resulting file will contain no audio!<br/>![warning] **WARNING:** Invalid `options` could result in script failure!
+-e, --extension|\<extension\>|Sets the output file extension.<br/>The extension may be prefixed by a dot (".") or not.<br/>Example: .ogg<br/>**Note:** Requires the `-a` option to also be specified. May not be specified with `-v` or `-b`.
+-f, --file|<audio_file>|If included, the script enters **[Batch Mode](./README.md#batch-mode)** and converts the specified audio file.<br/>![warning] **WARNING:** Do not use this argument when called from Lidarr!
 -o, --output|\<directory\>|Converted audio file(s) are saved to `directory` instead of being located in the same directory as the source audio file.<br/>The path will be created if it does not exist.
 -k, --keep-file| |Do not delete the source file or move it to the Lidarr Recycle bin.<br/>**Note:** This also disables triggering a Lidarr rescan after conversion.
+-r, --regex|'\<regex\>'|Sets the regular expression used to select input files.<br/>The `regex` value should be enclosed in single quotes and escaped properly.<br/>Defaults to `"\.flac$"`.
+-t, --tags|\<taglist\>|Comma separated list of metadata tags to apply automated corrections to.<br/>See [Metadata Corrections](./README.md#metadata-corrections) section.
 --help| |Display help and exit.
 --version| |Display version and exit.
 
@@ -91,28 +92,42 @@ The `-a` option effectively makes the script a generic wrapper for ffmpeg.  FFmp
 
 The exact format of the executed ffmpeg command is:
 ```
-ffmpeg -loglevel error -i "input.flac" ${options} "output.${extension}"
+ffmpeg -loglevel error -nostdin -i "input.flac" ${options} "output.${extension}"
+```
+
+#### Technical notes on regex
+By default, the script only matches and interacts with FLAC files (specifically, files ending in ".flac"). The `-r` option allows the script to match on a user specified regular expression (i.e. "regex") pattern. 
+
+Files are passed to the script with the full Linux path intact. (Ex: `/path/to/audio/a-ha/Hunting High and Low/01 Take on Me.mp3`).  Craft your regex with this in mind.
+
+![warning] **NOTE:** Escaping special regex characters (like a dot `.`) requires a double backslash, _even when single quoted!_ This is because **awk** (the program that processes audio files in the script) in most cases [strips a single backslash](https://www.gnu.org/software/gawk/manual/html_node/Escape-Sequences.html "GNU awk reference") from strings. Double quoted or unquoted strings require _four_ backslashes to preserve a regex escape because the bash shell will process the escapes first.
+
+For example, to convert all audio files to AAC audio files, use the following options:  
+```
+-a "-y -map 0 -c:a aac -b:a 240k -c:v copy" -e m4a --regex '\\.[^.]*$'
 ```
 
+Regular expression syntax is beyond the scope of this document.  See this [tutorial](https://www.regular-expressions.info/tutorial.html "Regular Expressions Tutorial") for more information. Regex patterns may be tested [here](http://regexstorm.net/tester "regex tester").
+
 ### Examples
 ```
 -b 320k        # Output 320 kbit/s MP3 (non-VBR; same as default behavior)
 -v 0           # Output variable bitrate MP3, VBR 220-260 kbit/s
 -d -b 160k     # Enable debugging level 1, and output a 160 kbit/s MP3
+-r '\\.[^.]*$' # Convert any file to MP3 (not just FLAC)
 -a "-c:v libtheora -map 0 -q:v 10 -c:a libopus -b:a 192k" -e .opus
-               # Convert to Opus format, VBR 192 kbit/s, cover art, no overwright
+               # Convert to Opus format, 192 kbit/s, cover art
+-a "-vn -c:a libopus -b:a 192K" -e .opus -r '\.mp3$'
+               # Convert .mp3 files to Opus format, 192 kbit/s, no cover art
 -a "-y -map 0 -c:a aac -b:a 240k -c:v copy" -e mp4
                # Convert to MP4 format, using AAC 240 kbit/s audio, cover art, overwrite file
 --file "/path/to/audio/a-ha/Hunting High and Low/01 Take on Me.flac"
                # Batch Mode
                # Output 320kbit/s MP3
 -o "/path/to/audio" -k
-               # Place the converted file(s) in the specified directory and do not delete the original audio file(s).
+               # Place the converted file(s) in the specified directory and do not delete the original audio file(s)
 ```
 
-### Wrapper Scripts
-To supply arguments to the script, one of the included wrapper scripts may be used or a custom wrapper script must be created.
-
 #### Included Wrapper Scripts
 For your convenience, several wrapper scripts are included in the `/usr/local/bin/` directory.  
 You may use any of these scripts in place of the `flac2mp3.sh` mentioned in the [Installation](./README.md#installation) section above.
@@ -141,6 +156,26 @@ Then put `/config/flac2mp3-custom.sh` in the **Path** field in place of `/usr/lo
 
 >**Note:** If you followed the Linuxserver.io recommendations when configuring your container, the `/config` directory will be mapped to an external storage location.  It is therefore recommended to place custom scripts in the `/config` directory so they will survive container updates, but they may be placed anywhere that is accessible by Lidarr.
 
+### Environment Variable
+The `flac2mp3.sh` script also allows the use of arguments provided by the `FLAC2MP3_ARGS` environment variable. This allows advanced use cases without having to provide a custom script.
+
+For example, the following value would convert any .mp3 to Opus:
+```
+-e FLAC2MP3_ARGS='-a "-vn -c:a libopus -b:a 192k" -e .opus -r "\\.mp3$"'
+```
+
+Make sure to correctly use quotes and/or escape special characters when using this method. (See [regex notes](./README.md#technical-notes-on-regex) above.)  
+In Docker Compose, the previous command would need an extra `$` to match the end-of-line:
+```yaml
+environment:
+  - FLAC2MP3_ARGS=-a "-vn -c:a libopus -b:a 192k" -e .opus -r '\\.mp3$$'
+```
+
+*Example Synology Configuration*  
+![flac2mp3](.assets/lidarr-synology-2.png "Synology container settings")
+
+>**NOTE:** The environment variable settings are _only_ used when **no** command line arguments are present. **Any** command line argument will disable the use of the environment variable.
+
 ### Triggers
 The only events/notification triggers that are supported are **On Release Import** and **On Upgrade**
 
@@ -171,6 +206,21 @@ This log can be downloaded from Lidarr under *System* > *Log Files*
 Log rotation is performed, with 5 log files of 1MB each kept, matching Lidarr's log retention.
 >![danger] **NOTE:** If debug logging is enabled with a level above 1, the log file can grow very large very quickly and is much more likely to be rotated.  *Do not leave high-level debug logging enabled permanently.*
 
+#### Metadata Corrections
+This feature is not meant for general purpose use. It is only documented for completeness.
+
+List of supported tags and metadata corrections that are applied:
+
+|Tag|Original|Correction
+|---|---|---
+|disc|1|1/1
+|genre|/Pop/|"Pop"
+| |/Indie/|"Alternative & Indie"
+| |/Industrial/|"Industrial Rock"
+| |/Electronic/|"Electronica & Dance"
+| |/Punk\|Alternative/|"Alternative & Punk"
+| |/Rock/|"Rock"
+
 ## Credits
 This would not be possible without the following:
 

.assets/lidarr-synology.png

@@ -6,8 +6,8 @@ Only the latest major and minor version are supported.
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 2.0.x   | :heavy_check_mark: |
-| < 2.0   | :x:                |
+| 2.2.x   | :heavy_check_mark: |
+| < 2.2   | :x:                |
 
 ## Reporting a Vulnerability
 

README.md

@@ -44,4 +44,3 @@ if [ ! -x /usr/local/bin/flac2mp3.sh ]; then
   echo "Making scripts executable."
   chmod +x /usr/local/bin/flac2*.sh
 fi
-

SECURITY.md

@@ -4,28 +4,33 @@ cat <<EOF
 ----------------
 >>> Flac2MP3 Mod by TheCaptain989 <<<
 Repos:
-Dev/test: https://github.com/TheCaptain989/lidarr-flac2mp3
-Prod: https://github.com/linuxserver/docker-mods/tree/lidarr-flac2mp3
+  Dev/test: https://github.com/TheCaptain989/lidarr-flac2mp3
+  Prod: https://github.com/linuxserver/docker-mods/tree/lidarr-flac2mp3
 
 Version: {{VERSION}}
 ----------------
 EOF
 
 # Determine if setup is needed
 if [ ! -f /usr/bin/ffmpeg ]; then
-    echo "**** Adding ffmpeg to package install list ****"
-    echo "ffmpeg" >> /mod-repo-packages-to-install.list
+  echo "**** Adding ffmpeg to package install list ****"
+  echo "ffmpeg" >> /mod-repo-packages-to-install.list
+else
+  echo "**** flac2mp3 deps already installed, skipping ****"
 fi
 
-# Change ownership
-if [ $(stat -c '%G' /usr/local/bin/flac2mp3.sh) != "abc" ]; then
-    echo "Changing ownership on scripts."
-    chown abc:abc /usr/local/bin/flac2*.sh
-fi
-
-# Make executable
-if [ ! -x /usr/local/bin/flac2mp3.sh ]; then
-    echo "Making scripts executable."
-    chmod +x /usr/local/bin/flac2*.sh
-fi
+# Check ownership and attributes on each script file
+for file in /usr/local/bin/flac2mp3*.sh
+do
+  # Change ownership
+  if [ $(stat -c '%G' $file) != "abc" ]; then
+    echo "Changing ownership on $file script."
+    chown abc:abc $file
+  fi
 
+  # Make executable
+  if [ ! -x $file ]; then
+    echo "Making $file script executable."
+    chmod +x $file
+  fi
+done

root/etc/cont-init.d/98-flac2mp3

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+. /usr/local/bin/flac2mp3.sh --tags disc,genre