A versatile command line tool for automated verifying and transcoding of all your torrents.

Most gazelle based indexers/trackers are supported

• RED
• [new] OPS.

Tested on Linux, theoretically works on Windows.

Fully configurable, if there's something hard coded that you think should be configurable then open a discussion on GitHub.

Each source is verified to ensure:

• A lossless FLAC
• Not a scene, lossy, unconfirmed, or trumpable release
• Files match the torrent hash
• Audio tags for artist, album, title and track number are set
• [fixed] Classical sources have a composer tag.
• [fixed] Vinyl track numbering is converted to numeric
• Sample rate and channels are suitable

• Full and zoomed spectrograms generated for review

• [fixed] Multi-threaded transcoding with optional CPU limit
• FLAC and FLAC 24 bit sources are supported
• FLAC, MP3 320 (CBR) and MP3 V0 (VBR) target formats
• Existing formats are skipped
• [fixed] Nested sub directories are fully supported (i.e. CD1, and CD2 etc)
• [fixed] Automatic naming following established conventions, with decoding of HTML entities.
• [fixed] Shorter file names.
• Automatic torrent file creation
• [new] Images in the root and first nested directory are included and all other files ignored.
• [new] Images larger than 750 KB are reduced to less than 1280 px, converted to JPG and compressed.

• Copy transcodes to content directory
• Copy torrent file to client auto-add directory

• [new] Verify, transcode and upload with one command for every torrent file in a directory.
• [new] Source torrents are added to a queue to track their progress reducing duplicate work and speeding up subsequent runs.

The application will crunch through your torrent directory and automatically determine which are FLAC sources suitable for transcoding.

Docker is the recommended way to run the application across all platforms.

• All dependencies are built into the image
• Runs in an isolated environment reducing risks to your system

Install Docker Engine for your OS.

Run the help command to see the available commands and options.

docker run ghcr.io/rogueoneecho/caesura --help

docker run ghcr.io/rogueoneecho/caesura verify --help

Create a config.yml file with the following content:

• announce_url Your personal announce URL. Find it on upload page.
• api_key Create an API key with Torrents permission Settings > Access Settings > Create an API Key

Refer to CONFIG.md for full documentation of options.

announce_url: https://flacsfor.me/YOUR_ANNOUNCE_KEY/announce
api_key: "YOUR_API_KEY"

You can then run the config command to see how the full configuration including default values the application will use:

docker run -v ./config.yml:/config.yml ghcr.io/rogueoneecho/caesura config

Create a directory for the application to output files to:

mkdir ./output

Create a directory for the application to cache files to:

mkdir ./cache

Run the verify command with the source as an argument.

docker run \
-v ./config.yml:/config.yml \
-v /path/to/your/content:/content \
-v ./output:/output \
-v ./cache:/cache \
ghcr.io/rogueoneecho/caesura \
verify https://redacted.sh/torrents.php?id=80518&torrentid=142659#torrent142659

If it looks good you can proceed to the next step, otherwise try another source.

Docker is great but specifying the volumes everytime is tedious and prone to error.

Using Docker Compose simplifies this by storing the configuration in a docker-compose.yml file.

Create a docker-compose.yml file with the following content:

services:
  caesura:
    container_name: caesura
    image: ghcr.io/rogueoneecho/caesura
    volumes:
    - ./config.yml:/config.yml:ro
    - /path/to/your/content:/content:ro
    - ./output:/output
    - ./cache:/cache

Now run the verify command again but this time using Docker Compose:

docker compose run --rm caesura verify 142659

Run the spectrogram command with the source as an argument.

docker compose run --rm caesura spectrogram 142659

Inspect the spectrograms in the output directory.

Run the transcode command with the source as an argument.

docker compose run --rm caesura transcode "Khotin - Hello World [2014].torrent"

Inspect the transcodes in the output directory.

Two .torrent files are created for each transcode, one with the indexer as a suffix (*.red.torrent or *.ops.torrent) and one without. For now these files are identical but if you subsequently transcode the same source for a different indexer they may differ.

Run the upload command with the source as an argument.

docker compose run --rm caesura upload https://redacted.sh/torrents.php?id=80518&torrentid=142659#torrent142659

If you haven't already then add the *.red.torrent or *.ops.torrent file to your torrent client.

copy_torrent_to: path/to/autoadd/directory

Go to your indexer and check your uploads to make sure everything has gone to plan.

Now that you have the hang of the application we can speed things up with the queue and batch commands.

The batch command handles verify, spectrogram, transcode and upload in a single command.

Run the queue add command to search through a directory of torrents and queue them for batch processing:

docker compose run --rm caesura queue add /path/to/your/torrents

Run the queue list command to see what is next in the queue for the current indexer:

docker compose run --rm caesura queue list

By default the batch command will limit to processing just 3 transcodes and it won't create spectrograms or upload unless explicitly instructed. These safeguards are in place to prevent mistakenly uploading a bunch of sources that you haven't checked.

Run the command to batch verify and transcode the three sources in the queue:

docker compose run --rm caesura batch --transcode

If everything goes to plan three sources should have transcoded to your output directory.

Use the queue summary command to see the progress:

docker compose run --rm caesura queue summary

Nothing was uploaded in the previous run of the batch command giving you a chance to check the transcodes and spectrograms. Once you're satisfied run again but with the --upload flag.

docker compose run --rm caesura batch --transcode --upload

Check the uploads on your indexer to make sure everything has gone to plan.

Now, we can set the batch command loose with the --no-limit option to transcode (but not upload) every source in the directory:

docker compose run --rm caesura batch --transcode --no-limit

Once you've checked the transcodes you can start to upload them in batches. The --wait-before-upload 30s option will add a 30 second wait interval between uploads to give you time to check everything looks good, and spread out the load on your indexer:

docker compose run --rm caesura batch --upload --limit 10 --wait-before-upload 30s

Check out the full documentation of configuration options in CONFIG.md, in particular you may want to use --copy-transcode-to-content-dir and --copy-torrent-to to suit your preferred setup.

caesura is designed to work with both RED and OPS. There's no need for separate cache or output directories, however, you will need a separate configuration for each and the commands must be run separately.

Make a copy of config.yml for each indexer. For clarity I recommend naming them config.red.yml and config.ops.yml

cp config.yml config.red.yml
cp config.yml config.ops.yml

Edit each config file to include the API key and announce URL for that indexer.

announce_url: https://home.opsfet.ch/YOUR_ANNOUNCE_KEY/announce
api_key: "YOUR_API_KEY"

Edit docker-compose.yml to include separate services for each indexer. The only difference between them is the mapping of the the config file.

services:

  caesura-red:
    container_name: caesura-red
    image: ghcr.io/rogueoneecho/caesura
    volumes:
    - ./config.red.yml:/config.yml:ro
    - /path/to/your/content:/content:ro
    - ./output:/output
    - ./cache:/cache

  caesura-ops:
    container_name: caesura-ops
    image: ghcr.io/rogueoneecho/caesura
    volumes:
    - ./config.ops.yml:/config.yml:ro
    - /path/to/your/content:/content:ro
    - ./output:/output
    - ./cache:/cache

Run the config command to verify the config is loaded correctly for each:

docker compose run --rm caesura-red config
docker compose run --rm caesura-ops config

The queue command is indexer agnostic so as long as both configurations use the same cache it only needs to be run once.

docker compose run --rm caesura-red queue add /path/to/your/torrents

Then run the batch command for each indexer:

docker compose run --rm caesura-red batch --transcode --upload
docker compose run --rm caesura-ops batch --transcode --upload

Found existing 320 transcode
Found existing V0 transcode

The application requires two writable directories.

The verify command will download .torrent files for each source to {CACHE}/torrents/{ID}.{INDEXER}.torrent

The queue and batch commands will read and write the source statues to {CACHE}/queue/{FIRST_BYTE_OF_HASH}.yml

The spectrogram command will generate spectrograms inside to {OUTPUT}/{ARTIST} - {ALBUM} [{YEAR}] [{MEDIA} SPECTROGRAMS]/

The transcode command will transcode to {OUTPUT}/{ARTIST} - {ALBUM} [{YEAR}] [{MEDIA} {FORMAT}]/

Then transcode will create two .torrent files:

• {OUTPUT}/{ARTIST} - {ALBUM} [{YEAR}] [{MEDIA} {FORMAT}].{INDEXER}.torrent
• {OUTPUT}/{ARTIST} - {ALBUM} [{YEAR}] [{MEDIA} {FORMAT}].torrent

Configuration options are sourced first from the command line arguments, then from a configuration file.

By default the application loads config.yml from the current working directory, but this can be overridden with the --config <CONFIG_PATH> cli argument.

Most options have sensible defaults so the minimum required configuration is:

announce_url: https://flacsfor.me/YOUR_ANNOUNCE_KEY/announce
api_key: "YOUR_API_KEY"

This is based around the setup in this guide: how to set up Deluge via Proton VPN with port forwarding.

• /srv/shared is a shared between multiple containers, by mounting as a single volume hard linking is possible.
• /srv/deluge/state is the Deluge state directory, containing all .torrent files loaded in Deluge.
• /srv/shared/deluge is the Deluge download directory, containing all the content.

• source: /srv/deluge/state, in config.yml means the source can be ommitted from the command.

announce_url: https://flacsfor.me/YOUR_ANNOUNCE_KEY/announce
api_key: YOUR_API_KEY
content:
- /srv/shared/deluge
limit: 2
output: /srv/shared/caesura
source: /srv/deluge/state
verbosity: debug

• user: "1000:1001" ensures files have the same ownership as the host user (use the id command to find your user and group id).
• Only /srv/shared has write permissions, the other directories are read-only.
• command: batch runs the batch command by default.
• / is the working directory of the container so mounting the config to /config.yml means it's read by default.

services:

  caesura:
    container_name: caesura
    image: ghcr.io/rogueoneecho/caesura
    user: "1000:1001"
    volumes:
    - /srv/caesura/config.yml:/config.yml:ro
    - /srv/deluge/state:/srv/deluge/state:ro
    - /srv/shared:/srv/shared

The cache/queue uses a YAML file format that can be analyzed with yq.

Filter` to see what has been transcoded:

cat ./cache/queue/*.yml | yq 'map(select(.transcode != null))'

Or to see what has been skipped and why:

cat ./cache/queue/*.yml | yq 'map(select(.verify.verified == false))'

If you're working with a lot of files then less can be helpful:

cat ./cache/queue/*.yml | yq --colors  'map(select(.verify.verified == false)) | less -R

If you encounter any issues:

1. Check the logs for errors

The logging verbosity can be adjusted with the --verbosity <LOG-LEVEL> option. The available log levels are:

• warn only showing warnings and errors
• info will give an overview of what's happening
• debug provides insight into each step
• trace is detailed logging to see exactly what's happening

2. Ask ChatGPT

You might be surprised how often just copying and pasting the command and error message into ChatGPT can provide an instant solution.

3. Re-read the getting started guide
4. Ask for help in support discussion
5. If it's an idea or request for a new feature search for an existing or create a new idea discussion
6. If it's a bug report search for an existing or create a new issue

The build process is documented in BUILD.md

Releases and a full changelog are available via GitHub Releases.

Release versions follow the Semantic Versioning 2.0.0 specification.

Commit messages follow the Conventional commit specification.

DevYukine completed the initial work and released it as red_oxide under an MIT license.

RogueOneEcho forked the project to complete a major refactor, fix some issues, add new features and improve logging and error handling. The fork is released as caesura under an AGPL license.

The main difference between the former MIT license and the present AGPL license is that if you intend to distribute a modified version of the code - even to run it on a server - you must also provide the modified source code under an AGPL license.

This is often known as copyleft. The intent is to ensure that anyone taking advantage of this open source work are also contributing back to the open source community.

The code base has now adopted object oriented patterns with SOLID principles and dependency injection.

See also the list of contributors who participated in this project.