### Client Integration Examples

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Examples demonstrating how to integrate wrtag with various clients like cURL, Transmission, qBittorrent, and slskd.

```APIDOC
## Client Integration Examples

### cURL Examples

**Copy release from path, attempt to match and tag:**
```bash
curl \
    --request POST \
    --data-urlencode "path=/path/to/the/release" \
    "https://:my-api-key@wrtag.hostname/op/copy"
```

**Reflink release from path, bypass match score check:**
```bash
curl \
    --request POST \
    --data-urlencode "path=/path/to/the/release" \
    --data-urlencode "confirm=true" \
    "https://:my-api-key@wrtag.hostname/op/reflink"
```

**Move release from path using a specific MBID:**
```bash
curl \
    --request POST \
    --data-urlencode "path=/path/to/the/release" \
    --data-urlencode "mbid=https://musicbrainz.org/release/d800f372-9673-4edf-8046-8baf79134257" \
    "https://:my-api-key@wrtag.hostname/op/move"
```

**Copy release from path and force-tag with the supplied MBID:**
```bash
curl \
    --request POST \
    --data-urlencode "path=/path/to/the/release" \
    --data-urlencode "mbid=https://musicbrainz.org/release/d800f372-9673-4edf-8046-8baf79134257" \
    --data-urlencode "confirm=true" \
    "https://:my-api-key@wrtag.hostname/op/copy"
```

### Transmission Integration

**`done.sh` script:**
```bash
#!/bin/sh

curl \
    --request POST \
    --data-urlencode "path=<path to downloads>/$TR_TORRENT_NAME" \
    "https://:<wrtag api key>@<wrtag host>/op/copy"
```

**Transmission `settings.json` configuration:**
```json
...
"script-torrent-done-enabled": true,
"script-torrent-done-filename": "/scripts/done.sh",
...
```

### qBittorrent Integration

**`done.sh` script:**
```bash
#!/bin/sh

echo "category: $1"
echo "path: $2"

[ "$1" != "music" ] && exit

curl \
    --request POST \
    --data-urlencode "path=$2" \
    "https://:<wrtag api key>@<wrtag host>/op/copy"
```

**qBittorrent configuration:**
`Tools` > `Options` > `Downloads` > `Run external program` > `Run on torrent finished` with path to `done.sh` and arguments like `/path/to/done.sh "%L" "%R"`.

### slskd Integration

**`autotag.sh` script:**
```bash
#!/usr/bin/bash
download_path=$(echo "${SLSKD_SCRIPT_DATA}" | jq -r .localDirectoryName)

wget -q -O/dev/null \
    --post-data "path=${download_path}" \
    "https://'':<wrtag api key>@<wrtag host>/op/move"

# if you have curl available then
# curl \
#     --request POST \
#     --data-urlencode "path=${download_path}" \
#     "https://:<wrtag api key>@<wrtag host>/op/move"
```

**slskd `config.yaml` configuration:**
```yaml
integration:
  scripts:
    write_tags:
      on:
        - DownloadDirectoryComplete
      run:
        command: "/autotag.sh"
```
```

--------------------------------

### Go Text/Template Path Formatting Examples

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Demonstrates various ways to format file paths using Go's text/template engine and custom helper functions. These examples cover complex scenarios like multi-album artist support, release year, disambiguations, disc/media numbering, track numbering, and compilation handling.

```Go
/music/{{ artists .Release.Artists | sort | join "; " | safepath }}/({{ .Release.ReleaseGroup.FirstReleaseDate.Year }}) {{ .Release.Title | safepath }}{{ if not (eq .ReleaseDisambiguation "") }} ({{ .ReleaseDisambiguation | safepath }}){{ end }}/{{ if gt (len .Release.Media) 1 }}d{{ pad0 2 .Media.Position }} {{ end }}{{ pad0 2 .Track.Position }}.{{ .Media.TrackCount | pad0 2 }} {{ if .IsCompilation }}{{ artistsString .Track.Artists | safepath }} - {{ end }}{{ .Track.Title | safepath }}{{ .Ext }}
```

```Go
/music/{{ artists .Release.Artists | join "; " | safepath }}/{{ .Release.Title | safepath }}/{{ pad0 2 .Track.Position }} {{ .Track.Title | safepath }}{{ .Ext }}
```

```Go
/music/{{ artists .Release.Artists | sort | join "; " | safepath }}/({{ .Release.ReleaseGroup.FirstReleaseDate.Year }}) {{ .Release.Title | safepath }}{{ if not (eq .ReleaseDisambiguation "") }} ({{ .ReleaseDisambiguation | safepath }}){{ end }}/{{ pad0 2 .Track.Position }} {{ .Track.Title | safepath }}{{ .Ext }}
```

```Go
/music/{{ artists .Release.Artists | sort | join "; " | safepath }}/({{ .Release.ReleaseGroup.FirstReleaseDate.Year }}) {{ .Release.Title | safepath }}/{{ pad0 2 .Track.Position }} {{ if .IsCompilation }}{{ artistsString .Track.Artists | safepath }} - {{ end }}{{ .Track.Title | safepath }}{{ .Ext }}
```

```Go
/music/{{ artists .Release.Artists | sort | join "; " | safepath }}/({{ .Release.ReleaseGroup.FirstReleaseDate.Year }}) {{ .Release.Title | safepath }}/{{ pad0 2 .Track.Position }}.{{ .Media.TrackCount | pad0 2 }} {{ .Track.Title | safepath }}{{ .Ext }}
```

--------------------------------

### Wrtag Path Format Examples (Linux/macOS)

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Provides examples of the `path-format` configuration option using Go's text/template syntax for Linux and macOS. It includes placeholders for artist, release, and track information, along with the file extension.

```go-template
path-format /music/library/{{ <some artist format> }}/({{ <some release format> }}/{{ <track format> }}
/music/library/Tame Impala/(2010) Innerspeaker/01. It Is Not Meant to Be.flac
/music/library/Tame Impala/(2010) Innerspeaker/02. Desire Be Desire Go.flac
/music/library/Tame Impala/(2010) Innerspeaker/03. Alter Ego.flac
```

--------------------------------

### Build wrtag from Source

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Instructions for building the wrtag project from source code using Go. It mentions the requirement for a recent Go toolchain and the command to install the binaries. It also notes that CGO is not required and how to build a static binary.

```bash
go install ./cmd/...
```

```bash
CGO_ENABLED=0
```

--------------------------------

### Configure and Run wrtagweb

Source: https://context7.com/sentriz/wrtag/llms.txt

The wrtagweb tool starts a web server for queue-based imports. Configuration can be passed via CLI flags or environment variables, defining the API key, database path, and path formatting templates.

```bash
wrtagweb \
  -web-api-key "your-secret-api-key" \
  -web-listen-addr ":7373" \
  -web-db-path "/data/wrtag.db" \
  -web-public-url "https://wrtag.example.com" \
  -path-format '/music/{{ artists .Release.Artists | join "; " | safepath }}/{{ .Release.Title | safepath }}/{{ pad0 2 .Track.Position }} {{ .Track.Title | safepath }}{{ .Ext }}'

export WRTAG_PATH_FORMAT='/music/{{ artists .Release.Artists | join "; " | safepath }}/{{ .Release.Title | safepath }}/{{ pad0 2 .Track.Position }} {{ .Track.Title | safepath }}{{ .Ext }}'
export WRTAG_WEB_API_KEY="your-secret-api-key"
export WRTAG_WEB_LISTEN_ADDR=":7373"
export WRTAG_WEB_DB_PATH="/data/wrtag.db"
wrtagweb
```

--------------------------------

### Wrtag Addon Configuration Examples

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Illustrates different ways to configure and activate wrtag addons, including command-line arguments, environment variables, and configuration files. Addons extend wrtag's functionality for fetching and processing metadata.

```Shell
$ wrtag -addon "lyrics a b c" -addon "replaygain x y z"
```

```Shell
$ WRTAG_ADDON="lyrics a b c,replaygain" wrtag
```

--------------------------------

### Deploy with Docker Compose

Source: https://context7.com/sentriz/wrtag/llms.txt

Example configuration for running wrtag as a containerized service using Docker Compose.

```yaml
services:
  wrtag:
    image: sentriz/wrtag
    environment:
      - WRTAG_WEB_API_KEY=your-secure-api-key
      - WRTAG_ADDON=lyrics lrclib genius,replaygain
    volumes:
      - ./data:/data
      - /path/to/music:/music
```

--------------------------------

### Wrtag Path Format Examples (Windows)

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Demonstrates the `path-format` configuration option for Windows systems, utilizing Go's text/template syntax with Windows-style drive letters and backslashes for organizing music files.

```go-template
path-format C:\User\John\Music\{{ <some artist format> }}\{{ <some release format> }}\{{ <track format> }}
```

--------------------------------

### Wrtag CLI Argument Examples

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Demonstrates how to use command-line interface (CLI) arguments with wrtag. Supports single and stackable arguments. Global arguments precede command-specific arguments.

```bash
wrtag -some-key "some value"
wrtag -some-key "value 1" -some-key "value 2"
wrtag <global options> cmd <cmd options>
```

--------------------------------

### Metadata Tool Usage Examples

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Demonstrates various ways to use the metadata tool for reading, writing, and clearing audio file metadata. It shows how to specify tags, values, and file paths, including reading from stdin and using wildcards.

```bash
metadata [<options>] read  <tag>... -- <path>...
metadata [<options>] write ( <tag> <value>... , )... -- <path>...
metadata [<options>] clear <tag>... -- <path>...

# <tag> is an audio metadata tag key
# <value> is an audio metadata tag value
# <path> is path(s) to audio files, dir(s) to find audio files in, or "-" for list audio file paths from stdin
```

```bash
metadata read -- a.flac b.flac c.flac
```

```bash
metadata read artist title -- a.flac
```

```bash
metadata read -properties -- a.flac
```

```bash
metadata read -properties title length -- a.flac
```

```bash
metadata write album "album name" -- x.flac
```

```bash
metadata write artist "Sensient" , genres "psy" "minimal" "techno" -- dir/*.flac
```

```bash
metadata write artist "Sensient" , genres "psy" "minimal" "techno" -- dir/
```

```bash
metadata clear -- a.flac
```

```bash
metadata clear lyrics artist_credit -- *.flac
```

```bash
find x/ -type f | metadata write artist "Sensient" , album "Blue Neevus" -
```

```bash
find y/ -type f | metadata read artist title -
```

```bash
find y/ -type f -name "*extended*" | metadata read -properties length -
```

--------------------------------

### wrtag API POST Operations (cURL)

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Examples demonstrating how to use cURL to send POST requests to the wrtag API for copy, move, and reflink operations. These examples show how to include paths, optional MusicBrainz IDs, and confirmation flags.

```bash
curl \
    --request POST \
    --data-urlencode "path=/path/to/the/release" \
    "https://:my-api-key@wrtag.hostname/op/copy"

curl \
    --request POST \
    --data-urlencode "path=/path/to/the/release" \
    --data-urlencode "confirm=true" \
    "https://:my-api-key@wrtag.hostname/op/reflink"

curl \
    --request POST \
    --data-urlencode "path=/path/to/the/release" \
    --data-urlencode "mbid=https://musicbrainz.org/release/d800f372-9673-4edf-8046-8baf79134257" \
    "https://:my-api-key@wrtag.hostname/op/move"

curl \
    --request POST \
    --data-urlencode "path=/path/to/the/release" \
    --data-urlencode "mbid=https://musicbrainz.org/release/d800f372-9673-4edf-8046-8baf79134257" \
    --data-urlencode "confirm=true" \
    "https://:my-api-key@wrtag.hostname/op/copy"
```

--------------------------------

### Wrtag Environment Variable Examples

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Illustrates the use of environment variables for configuring wrtag, prefixed with WRTAG_. Stackable arguments are comma-separated. Commas within values can be escaped.

```bash
WRTAG_LOG_LEVEL=info wrtag
WRTAG_ADDON="replaygain,lyrics genius musixmatch"
WRTAG_ADDON="value1\,value2"
```

--------------------------------

### Integrate wrtag API with slskd (Bash/jq)

Source: https://github.com/sentriz/wrtag/blob/master/README.md

A bash script for slskd integration using its 'scripts' configuration. It parses the SLSKD_SCRIPT_DATA environment variable to get the download path and then uses wget (or curl) to send a POST request to the wrtag API for moving the release.

```bash
#!/usr/bin/bash
download_path=$(echo "${SLSKD_SCRIPT_DATA}" | jq -r .localDirectoryName)

# wget is the only thing available in the slskd container
wget -q -O/dev/null \
    --post-data "path=${download_path}" \
    "https://'':<wrtag api key>@<wrtag host>/op/move"

# if you have curl available then
# curl \
#     --request POST \
#     --data-urlencode "path=${download_path}" \
#     "https://:<wrtag api key>@<wrtag host>/op/move"
```

--------------------------------

### GET /release

Source: https://github.com/sentriz/wrtag/blob/master/cmd/wrtag/testdata/responses/musicbrainz/ws/2/release/index.html

Retrieves a list of music releases based on search criteria or identifiers.

```APIDOC
## GET /release

### Description
Retrieves a collection of music releases with associated metadata such as artist credits, release groups, and label information.

### Method
GET

### Endpoint
/release

### Parameters
#### Query Parameters
- **offset** (integer) - Optional - The number of records to skip for pagination.

### Request Example
GET /release?offset=0

### Response
#### Success Response (200)
- **count** (integer) - Total number of releases found.
- **releases** (array) - List of release objects containing metadata.

#### Response Example
{
  "count": 1757033,
  "offset": 0,
  "releases": [
    {
      "id": "e47d04a4-7460-427d-a731-cc82386d85f1",
      "title": "Kat Moda",
      "status": "Official",
      "artist-credit": [{"name": "Jeff Mills"}],
      "track-count": 3
    }
  ]
}
```

--------------------------------

### GET /metadata/tags

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Retrieves the standard metadata tag definitions supported by the wrtag system.

```APIDOC
## GET /metadata/tags

### Description
Provides a comprehensive list of supported metadata tags and their descriptions for audio file tagging.

### Method
GET

### Endpoint
/metadata/tags

### Parameters
None

### Response
#### Success Response (200)
- **COMPILATION** (string) - Indicates if the release is by various artists.
- **RELEASETYPE** (array) - Primary and secondary release types (e.g., album, soundtrack).
- **TITLE** (string) - Track title.
- **ARTIST** (string) - Track artist as a single string.
- **ARTISTS** (array) - Track artist names as multi-valued tags.
- **ARTIST_CREDIT** (string) - Track artist credit as a single string.
- **ARTISTS_CREDIT** (array) - Track artist credit names as multi-valued tags.
- **GENRE** (string) - Primary genre.
- **GENRES** (array) - Genre list as multi-valued tags.
- **TRACKNUMBER** (integer) - Track number.
- **TRACKTOTAL** (integer) - Total tracks on disc/media.
- **DISCNUMBER** (integer) - Disc/media number.
- **DISCTOTAL** (integer) - Total discs/medias in release.
- **DISCSUBTITLE** (string) - Disc/media subtitle.
- **ISRC** (string) - International Standard Recording Code.

#### Response Example
{
  "TITLE": "America Is Waiting",
  "ARTIST": "Brian Eno + David Byrne",
  "GENRE": "ambient",
  "TRACKNUMBER": 1
}
```

--------------------------------

### Get Release Images

Source: https://github.com/sentriz/wrtag/blob/master/cmd/wrtag/testdata/responses/coverartarchive/release/e47d04a4-7460-427d-a731-cc82386d85f1/index.html

Retrieves image information associated with a specific release. This includes details like approval status, image file paths, and thumbnail URLs.

```APIDOC
## GET /sentriz/wrtag/release/{release_id}/images

### Description
Retrieves a list of images associated with a specific release ID. The response includes details about each image, such as its approval status, file path, and available thumbnail sizes.

### Method
GET

### Endpoint
/sentriz/wrtag/release/{release_id}/images

### Parameters
#### Path Parameters
- **release_id** (string) - Required - The unique identifier for the release.

### Response
#### Success Response (200)
- **images** (array) - A list of image objects.
  - **approved** (boolean) - Indicates if the image is approved.
  - **back** (boolean) - Indicates if the image is a back image.
  - **comment** (string) - Any comments associated with the image.
  - **edit** (integer) - An edit identifier for the image.
  - **front** (boolean) - Indicates if the image is a front image.
  - **id** (integer) - The unique identifier for the image.
  - **image** (string) - The file path to the main image.
  - **thumbnails** (object) - An object containing URLs for different thumbnail sizes.
    - **1200** (string) - URL for the 1200px thumbnail.
    - **250** (string) - URL for the 250px thumbnail.
    - **500** (string) - URL for the 500px thumbnail.
    - **large** (string) - URL for the large thumbnail.
    - **small** (string) - URL for the small thumbnail.
  - **types** (array) - A list of types associated with the image (e.g., "Front").
- **release** (string) - The file path to the release information.

#### Response Example
```json
{
  "images": [
    {
      "approved": true,
      "back": false,
      "comment": "",
      "edit": 90870637,
      "front": true,
      "id": 32921095540,
      "image": "file:///testdata/responses/coverartarchive/release/e47d04a4-7460-427d-a731-cc82386d85f1/32921095540.jpg",
      "thumbnails": {
        "1200": "file:///coverartarchive/release/e47d04a4-7460-427d-a731-cc82386d85f1/32921095540-1200.jpg",
        "250": "file:///coverartarchive/release/e47d04a4-7460-427d-a731-cc82386d85f1/32921095540-250.jpg",
        "500": "file:///coverartarchive/release/e47d04a4-7460-427d-a731-cc82386d85f1/32921095540-500.jpg",
        "large": "file:///coverartarchive/release/e47d04a4-7460-427d-a731-cc82386d85f1/32921095540-500.jpg",
        "small": "file:///coverartarchive/release/e47d04a4-7460-427d-a731-cc82386d85f1/32921095540-250.jpg"
      },
      "types": [
        "Front"
      ]
    }
  ],
  "release": "file:///testdata/responses/musicbrainz/release/e47d04a4-7460-427d-a731-cc82386d85f1"
}
```
```

--------------------------------

### Configure ReplayGain Addon

Source: https://context7.com/sentriz/wrtag/llms.txt

Sets up volume normalization using the rsgain binary. Options include true-peak calculation and forcing recalculation of existing values.

```bash
wrtag -addon "replaygain true-peak force" move "/downloads/Album"
export WRTAG_ADDON="replaygain true-peak"
wrtag move "/downloads/Album"
```

--------------------------------

### Wrtagweb CLI Options

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Displays the command-line interface options for the wrtagweb tool. This includes arguments, corresponding environment variables, and configuration file keys for various settings like API keys, authentication, database paths, and network listeners.

```bash
go run ./cmd/wrtagweb -h 2>&1 | ./gen-docs | wl-copy
```

--------------------------------

### Configure Path Format Templates

Source: https://context7.com/sentriz/wrtag/llms.txt

Define music library directory structures using Go template syntax. These templates leverage MusicBrainz release data to organize files.

```bash
path-format /music/{{ artists .Release.Artists | join "; " | safepath }}/{{ .Release.Title | safepath }}/{{ pad0 2 .Track.Position }} {{ .Track.Title | safepath }}{{ .Ext }}
path-format /music/{{ artists .Release.Artists | sort | join "; " | safepath }}/({{ .Release.ReleaseGroup.FirstReleaseDate.Year }}) {{ .Release.Title | safepath }}{{ if not (eq .ReleaseDisambiguation "") }} ({{ .ReleaseDisambiguation | safepath }}){{ end }}/{{ pad0 2 .Track.Position }}.{{ .Media.TrackCount | pad0 2 }} {{ if .IsCompilation }}{{ artistsString .Track.Artists | safepath }} - {{ end }}{{ .Track.Title | safepath }}{{ .Ext }}
path-format /music/{{ artists .Release.Artists | sort | join "; " | safepath }}/({{ .Release.ReleaseGroup.FirstReleaseDate.Year }}) {{ .Release.Title | safepath }}/{{ if gt (len .Release.Media) 1 }}d{{ pad0 2 .Media.Position }} {{ end }}{{ pad0 2 .Track.Position }} {{ .Track.Title | safepath }}{{ .Ext }}
```

--------------------------------

### Deploying wrtag with Docker Compose

Source: https://github.com/sentriz/wrtag/blob/master/README.md

A sample compose.yml file to deploy wrtag. It includes necessary environment variables for the web API, database paths, and volume mappings for persistent data and music files.

```yaml
services:
  wrtag:
    image: sentriz/wrtag
    environment:
      - WRTAG_PATH_FORMAT=
      - WRTAG_WEB_API_KEY=
      - WRTAG_WEB_LISTEN_ADDR=:80
      - WRTAG_WEB_PUBLIC_URL=https://wrtag.example.com
      - WRTAG_WEB_DB_PATH=/data/wrtag.db
      - WRTAG_LOG_LEVEL=debug
    expose:
      - 80
    volumes:
      - ./data:/data
      - /path/to/music:/path/to/music
```

--------------------------------

### Integrate with BitTorrent Clients

Source: https://context7.com/sentriz/wrtag/llms.txt

Bash script snippet for automating imports upon completion of downloads in clients like Transmission or qBittorrent.

```bash
#!/bin/bash
CATEGORY="$1"
TORRENT_PATH="${2:-$TR_TORRENT_DIR/$TR_TORRENT_NAME}"
```

--------------------------------

### Integrate wrtag API with qBittorrent (Bash)

Source: https://github.com/sentriz/wrtag/blob/master/README.md

A bash script designed for qBittorrent's 'Run external program' on torrent completion. It checks the download category and, if it's 'music', sends a POST request to the wrtag API to copy the release using the provided path argument.

```bash
#!/bin/sh

echo "category: $1"
echo "path: $2"

[ "$1" != "music" ] && exit

curl \
    --request POST \
    --data-urlencode "path=$2" \
    "https://:<wrtag api key>@<wrtag host>/op/copy"
```

--------------------------------

### Automate Music Import via qBittorrent Hook

Source: https://context7.com/sentriz/wrtag/llms.txt

A shell script snippet designed to be used as a post-download hook in qBittorrent. It filters for the music category and triggers the wrtag copy operation via a POST request to the web API.

```bash
# Only process music category (qBittorrent)
[ -n "$CATEGORY" ] && [ "$CATEGORY" != "music" ] && exit 0

curl \
    --request POST \
    --data-urlencode "path=$TORRENT_PATH" \
    "https://:your-api-key@wrtag.example.com/op/copy"
```

--------------------------------

### Wrtag Configuration File Format

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Shows the format for wrtag configuration files, which follows the flagconf structure. Keys correspond to arguments, and values are their settings. Stackable arguments are listed on separate lines with the same key.

```plaintext
some-key argument
other-key argument

addon replaygain
addon lyrics genius musixmatch
```

--------------------------------

### Move and Copy Music Files with wrtag

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Demonstrates how to use the move and copy subcommands to import music into a library. These commands support flags for dry runs, forced operations, and manual MusicBrainz ID overrides.

```console
wrtag move "Example"
wrtag move -dry-run "Example"
wrtag move -yes "Example"
wrtag move -mbid "abc" -yes "Example"
wrtag copy -yes "Example"
wrtag copy -mbid "abc" -yes
```

--------------------------------

### slskd Integration Configuration (YAML)

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Configuration snippet for slskd's config.yaml file, setting up script integration to run a custom script ('/autotag.sh') upon the 'DownloadDirectoryComplete' event.

```yaml
integration:
  scripts:
    write_tags:
      on:
        - DownloadDirectoryComplete
      run:
        command: "/autotag.sh"
```

--------------------------------

### Configure Subprocess Addon

Source: https://context7.com/sentriz/wrtag/llms.txt

Executes custom commands or scripts post-import. Uses placeholders like <files>, <cover>, and <directory> to pass context to external scripts.

```bash
wrtag -addon 'subproc my-script <files>' move "/downloads/Album"
wrtag -addon 'subproc optimize-cover <cover>' move "/downloads/Album"
```

--------------------------------

### Wrtag Tagging Process Overview

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Outlines the systematic steps wrtag follows during the music tagging process. This includes clearing existing tags, writing main tags from MusicBrainz, preserving default keep tags, and applying custom tag configuration rules.

```Text
1. All existing tags are cleared
2. Main tags are written
3. Default keep tags are preserved
4. Custom tag-config rules are applied
```

--------------------------------

### POST /op/<copy|move|reflink>

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Adds a job to the wrtag queue to process a specified path. Supports operations like copy, move, and reflink, with optional parameters for MusicBrainz ID and confirmation.

```APIDOC
## POST /op/<copy|move|reflink>

### Description
Adds a job to the wrtag queue to process a specified path. Supports operations like copy, move, and reflink, with optional parameters for MusicBrainz ID and confirmation.

### Method
POST

### Endpoint
`/op/<copy|move|reflink>`

### Parameters
#### Query Parameters
- **path** (string) - Required - The absolute path to the directory to process.
- **mbid** (string) - Optional - The MusicBrainz release URL to associate with the job.
- **confirm** (boolean) - Optional - If true, bypasses manual confirmation for matching.

### Request Example
```json
{
  "path": "/path/to/the/release",
  "mbid": "https://musicbrainz.org/release/d800f372-9673-4edf-8046-8baf79134257",
  "confirm": true
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of job submission.

#### Response Example
```json
{
  "message": "Job added to queue."
}
```
```

--------------------------------

### ReplayGain Addon Configuration

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Configures the replaygain addon to compute and embed ReplayGain 2.0 loudness information into audio files. It supports options like 'true-peak' and 'force' to recompute existing data.

```Shell
replaygain <opts>...
```

```Shell
true-peak
```

```Shell
force
```

--------------------------------

### Configure Notifications

Source: https://context7.com/sentriz/wrtag/llms.txt

Sets up event-based notifications using shoutrrr URIs for services like SMTP and HTTP webhooks.

```bash
wrtag -notification-uri "complete,needs-input smtp://user:pass@smtp.example.com:587/?from=wrtag@example.com&to=you@example.com" sync
wrtag -notification-uri "sync-complete generic+https://musicserver.local/api/scan?key=secret" sync
```

--------------------------------

### Re-tagging Music Releases

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Shows how to re-tag existing music releases using the move command for single items or the sync command for bulk library operations. Syncing allows for recursive processing and filtering by age or concurrency.

```console
wrtag move "/my/music/Tame Impala/(2010) Innerspeaker"
wrtag sync
wrtag sync -dry-run
wrtag sync "/my/music/Tame Impala"
wrtag sync -age-older 24h
wrtag sync -num-workers 16
```

--------------------------------

### Subprocess Addon Configuration

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Sets up the subprocess addon to execute a user-provided program with specified arguments. It includes a special placeholder '<files>' that expands to the paths of processed files.

```Shell
subproc <path> <args>...
```

```Shell
"subproc my-program a --b 'c d' <files>"
```

--------------------------------

### Configure Lyrics Addon

Source: https://context7.com/sentriz/wrtag/llms.txt

Enables the lyrics addon to fetch metadata from LRCLib, Genius, or Musixmatch. It supports CLI flags, environment variables, and configuration files.

```bash
wrtag -addon "lyrics lrclib genius musixmatch" move "/downloads/Album"
export WRTAG_ADDON="lyrics lrclib genius"
wrtag move "/downloads/Album"
```

--------------------------------

### Copy Music Files with wrtag

Source: https://context7.com/sentriz/wrtag/llms.txt

The copy command duplicates music files into the library while applying tags, ensuring the original source remains untouched. It accepts flags for forced imports and dry run previews.

```bash
wrtag copy "/downloads/Artist - Album"
wrtag copy -yes "/downloads/Artist - Album"
wrtag copy -mbid "3b28412d-8a47-3da9-8331-525947231d50" -yes "/downloads/Artist - Album"
wrtag copy -dry-run "/downloads/Artist - Album"
```

--------------------------------

### Read Audio Metadata Tags

Source: https://context7.com/sentriz/wrtag/llms.txt

Use the metadata CLI to read tags and audio properties. Supports filtering by specific tags, reading from directories, and processing input from stdin.

```bash
metadata read -- track1.flac track2.flac track3.flac
metadata read artist title album -- track.flac
metadata read -- /music/album/
metadata read -properties -- track.flac
metadata read -properties length bitrate -- track.flac
find /music -name "*.flac" | metadata read artist title -
find /music -name "*extended*" | metadata read -properties length -
```

--------------------------------

### Sync Library Metadata with wrtag

Source: https://context7.com/sentriz/wrtag/llms.txt

The sync command performs bulk re-tagging of an existing library. It supports filtering by file age, concurrent processing with worker threads, and dry run modes.

```bash
wrtag sync
wrtag sync -dry-run
wrtag sync "/music/Tame Impala"
wrtag sync -age-older 24h
wrtag sync -age-younger 168h
wrtag sync -num-workers 16
wrtag sync -age-older 24h -num-workers 8 -dry-run "/music"
```

--------------------------------

### Submit Import Jobs via Web API

Source: https://context7.com/sentriz/wrtag/llms.txt

External clients can trigger import operations by sending HTTP POST requests to the wrtagweb API. Authentication is handled via Basic Auth using the configured API key.

```bash
curl \
    --request POST \
    --data-urlencode "path=/downloads/Artist - Album" \
    "https://:your-api-key@wrtag.example.com/op/copy"
```

--------------------------------

### POST /op/copy

Source: https://context7.com/sentriz/wrtag/llms.txt

Adds a music import job to the wrtagweb queue using the copy operation. This endpoint allows external scripts to trigger library imports.

```APIDOC
## POST /op/copy

### Description
Adds a directory path to the wrtagweb import queue. The system will process the files, match them against MusicBrainz, and copy them to the library destination.

### Method
POST

### Endpoint
/op/copy

### Parameters
#### Request Body
- **path** (string) - Required - The absolute filesystem path to the source music directory.

### Request Example
curl -X POST --data-urlencode "path=/downloads/Artist - Album" "https://:your-api-key@wrtag.example.com/op/copy"

### Response
#### Success Response (200)
- **status** (string) - Confirmation that the job has been queued.

#### Response Example
{
  "status": "queued",
  "job_id": "12345"
}
```

--------------------------------

### Configure System Notifications via Shoutrrr

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Shows how to define notification URIs for specific events. The configuration links event names to shoutrrr-compatible service strings.

```text
complete,sync-complete smtp://username:password@host:port/?from=from@example.com&to=recipient@example.com
```

```text
sync-complete generic+https://my.subsonic.com/rest/startScan.view?c=wrtag&v=1.16&u=user&p=password
```

--------------------------------

### wrtag API Configuration (JSON)

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Configuration snippet for Transmission's settings.json file, enabling and specifying the path to a custom script that will be executed upon torrent completion.

```json
...
"script-torrent-done-enabled": true,
"script-torrent-done-filename": "/scripts/done.sh",
...
```

--------------------------------

### File Naming Convention for Multi-Media Releases

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Defines a file naming pattern for organizing music releases, incorporating artist, release year, title, media position, track position, and file extension. It uses Go templating for dynamic path generation.

```Go Template
/music/{{ artists .Release.Artists | sort | join "; " | safepath }}/({{ .Release.ReleaseGroup.FirstReleaseDate.Year }}) {{ .Release.Title | safepath }}/{{ .Media.Position }}-{{ pad0 2 .Track.Position }} {{ .Track.Title | safepath }}{{ .Ext }}
```

--------------------------------

### Reflink Music Files with wrtag

Source: https://context7.com/sentriz/wrtag/llms.txt

The reflink command creates space-efficient copy-on-write clones of music files on supported filesystems. This is ideal for maintaining library structure without duplicating actual data blocks.

```bash
wrtag reflink "/downloads/Artist - Album"
wrtag reflink -yes "/downloads/Artist - Album"
wrtag reflink -dry-run "/downloads/Artist - Album"
```

--------------------------------

### POST /op/copy

Source: https://context7.com/sentriz/wrtag/llms.txt

Copies a file, optionally using a MusicBrainz ID and forcing confirmation.

```APIDOC
## POST /op/copy

### Description
Copies a file to a new location. This operation can utilize a MusicBrainz ID for reference and allows for forced confirmation to bypass interactive prompts.

### Method
POST

### Endpoint
`https://:your-api-key@wrtag.example.com/op/copy`

### Parameters
#### Query Parameters
- **path** (string) - Required - The destination path for the copied file.
- **mbid** (string) - Optional - The MusicBrainz release ID to associate with the copy.
- **confirm** (boolean) - Optional - If `true`, bypasses confirmation prompts.

### Request Example
```json
{
  "path": "/downloads/Artist - Album",
  "mbid": "3b28412d-8a47-3da9-8331-525947231d50",
  "confirm": true
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of successful copy operation.

#### Response Example
```json
{
  "message": "File copied successfully."
}
```
```

--------------------------------

### Authentication

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Details on how to authenticate with the wrtag API using HTTP Basic Authentication.

```APIDOC
## Authentication

### Description
The external API requires HTTP Basic authentication. The username is omitted, and the password should be set to your `-web-api-key`.

### Method
HTTP Basic Authentication

### Credentials
- **Username**: (None)
- **Password**: `-web-api-key`

### Security Note
Ensure that the `wrtagweb` service is secured using TLS (HTTPS) to protect credentials transmitted over the network.
```

--------------------------------

### Manage Tag Configuration

Source: https://context7.com/sentriz/wrtag/llms.txt

Defines rules for keeping or dropping specific metadata tags during the import process. Supports CLI flags and environment variables.

```bash
wrtag -tag-config "keep CUSTOM_RATING" -tag-config "drop GENRE" move "/downloads/Album"
export WRTAG_TAG_CONFIG="keep CUSTOM_RATING,drop GENRE"
wrtag move "/downloads/Album"
```

--------------------------------

### Lyrics Addon Configuration

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Configures the lyrics addon to fetch lyric information from specified sources like LRCLib, Genius, or Musixmatch. It supports fetching synchronized LRC lyrics and plain text lyrics.

```Shell
lyrics <source>...
```

```Shell
"lyrics lrclib genius"
```

--------------------------------

### Configure Tag Preservation and Removal

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Demonstrates how to use the tag-config option to keep or drop specific metadata tags. This can be achieved via command-line arguments or environment variables.

```bash
wrtag -tag-config "keep CUSTOM_RATING" -tag-config "keep MOOD" -tag-config "drop GENRE"
```

```bash
export WRTAG_TAG_CONFIG="keep CUSTOM_RATING,keep MOOD,drop GENRE,drop COMMENT"
```

--------------------------------

### Write Audio Metadata Tags

Source: https://context7.com/sentriz/wrtag/llms.txt

Update or write tags to audio files using the metadata CLI. Supports multi-value tags, batch directory processing, and complex tag assignments.

```bash
metadata write album "My Album Name" -- track.flac
metadata write artist "Artist Name" , album "Album Name" -- track.flac
metadata write genres "electronic" "ambient" "experimental" -- track.flac
metadata write artist "Artist Name" , album "Album Name" -- /music/album/
find /music/album -type f | metadata write artist "Artist Name" , album "Album Name" -
metadata write artist "Brian Eno" , album "Ambient 1: Music for Airports" , genres "ambient" "electronic" , date "1978" -- track.flac
```

--------------------------------

### Move Music Files with wrtag

Source: https://context7.com/sentriz/wrtag/llms.txt

The move command tags and relocates music directories into a library structure. It supports dry runs, forced imports for low-confidence matches, and specific MusicBrainz ID overrides.

```bash
wrtag move "/downloads/Artist - Album"
wrtag move -dry-run "/downloads/Artist - Album"
wrtag move -yes "/downloads/Artist - Album"
wrtag move -mbid "3b28412d-8a47-3da9-8331-525947231d50" -yes "/downloads/Artist - Album"
WRTAG_LOG_LEVEL=debug wrtag move "/downloads/Artist - Album"
```

--------------------------------

### Notification System

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Configure event-based notifications using shoutrrr URIs.

```APIDOC
## Notification System

### Description
Configure external notifications for events such as import completion or sync status using shoutrrr URIs.

### Supported Events
- **complete** (wrtagweb) - Executed when a release is imported.
- **needs-input** (wrtagweb) - Executed when a release requires input.
- **sync-complete** (wrtag) - Executed when a sync has completed.
- **sync-error** (wrtag) - Executed when a sync has completed with errors.

### Configuration Format
`<eventspec> <shoutrrr_uri>`

### Example
`"complete,sync-complete smtp://username:password@host:port/?from=from@example.com&to=recipient@example.com"`
```

--------------------------------

### Integrate wrtag API with Transmission (Bash)

Source: https://github.com/sentriz/wrtag/blob/master/README.md

A bash script to be used with Transmission's 'script-torrent-done-enabled' feature. It sends a POST request to the wrtag API to copy a completed torrent's release, utilizing the TR_TORRENT_NAME environment variable.

```bash
#!/bin/sh

curl \
    --request POST \
    --data-urlencode "path=<path to downloads>/$TR_TORRENT_NAME" \
    "https://:<wrtag api key>@<wrtag host>/op/copy"
```

--------------------------------

### Music Descriptors Addon Configuration

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Configures the musicdesc addon to calculate and embed music descriptor information using the 'streaming_extractor_music' tool. The 'force' option can be used to recompute existing descriptor data.

```Shell
musicdesc <opts>...
```

```Shell
force
```

--------------------------------

### Perform wrtag API Operations

Source: https://context7.com/sentriz/wrtag/llms.txt

Execute file operations like move, reflink, and copy via the wrtag API using curl. These commands require an API key and support parameters for path, MusicBrainz IDs, and confirmation flags.

```bash
curl --request POST --data-urlencode "path=/downloads/Artist - Album" --data-urlencode "confirm=true" "https://:your-api-key@wrtag.example.com/op/move"
curl --request POST --data-urlencode "path=/downloads/Artist - Album" --data-urlencode "mbid=https://musicbrainz.org/release/3b28412d-8a47-3da9-8331-525947231d50" "https://:your-api-key@wrtag.example.com/op/reflink"
curl --request POST --data-urlencode "path=/downloads/Artist - Album" --data-urlencode "mbid=3b28412d-8a47-3da9-8331-525947231d50" --data-urlencode "confirm=true" "https://:your-api-key@wrtag.example.com/op/copy"
```

--------------------------------

### POST /op/move

Source: https://context7.com/sentriz/wrtag/llms.txt

Moves a file with optional auto-confirmation, bypassing score checks.

```APIDOC
## POST /op/move

### Description
Moves a file to a new path. If `confirm=true` is provided, the operation will proceed without requiring manual confirmation, effectively bypassing any score checks.

### Method
POST

### Endpoint
`https://:your-api-key@wrtag.example.com/op/move`

### Parameters
#### Query Parameters
- **path** (string) - Required - The destination path for the file.
- **confirm** (boolean) - Optional - If `true`, bypasses confirmation prompts.

### Request Example
```json
{
  "path": "/downloads/Artist - Album",
  "confirm": true
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of successful move.

#### Response Example
```json
{
  "message": "File moved successfully."
}
```
```

--------------------------------

### Manage Embedded Cover Art

Source: https://context7.com/sentriz/wrtag/llms.txt

Extract, embed, or clear cover art images from audio files. Supports indexing and metadata assignment for images.

```bash
metadata image-read -- track.flac > cover.jpg
metadata image-read -index 1 -- track.flac > back.jpg
metadata image-write cover.jpg -- track.flac
metadata image-write -index 0 -type "Front Cover" -desc "Album cover" cover.jpg -- track.flac
metadata image-write -index 1 -type "Back Cover" back.jpg -- track.flac
metadata image-clear -- track.flac
metadata image-write cover.jpg -- track1.flac track2.flac track3.flac
```

--------------------------------

### Tag Configuration

Source: https://github.com/sentriz/wrtag/blob/master/README.md

Configure how tags are preserved or removed during the tagging process.

```APIDOC
## Tag Configuration

### Description
The tag-config option allows users to define rules for keeping or dropping specific metadata tags during file processing.

### Parameters
#### Configuration Options
- **keep <tag>** (string) - Required - Preserve the specified tag from the original file.
- **drop <tag>** (string) - Required - Remove the specified tag from the final output.

### Usage Example
`$ wrtag -tag-config "keep CUSTOM_RATING" -tag-config "drop GENRE"`
```

--------------------------------

### POST /op/reflink

Source: https://context7.com/sentriz/wrtag/llms.txt

Reflinks a file using a MusicBrainz release ID, useful for linking files to specific releases.

```APIDOC
## POST /op/reflink

### Description
Reflinks a file, associating it with a specific MusicBrainz release ID. This is useful for ensuring accurate metadata and release information.

### Method
POST

### Endpoint
`https://:your-api-key@wrtag.example.com/op/reflink`

### Parameters
#### Query Parameters
- **path** (string) - Required - The path to the file to be reflinked.
- **mbid** (string) - Required - The MusicBrainz release ID (URL or just the ID).

### Request Example
```json
{
  "path": "/downloads/Artist - Album",
  "mbid": "https://musicbrainz.org/release/3b28412d-8a47-3da9-8331-525947231d50"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of successful reflink operation.

#### Response Example
```json
{
  "message": "File reflinked successfully."
}
```
```