4 releases

0.10.1	Jun 17, 2024

#112 in Audio

AGPL-3.0-only

200KB
5K SLoC

caesura 𝄓

An all-in-one command line tool to automate transcoding FLAC or FLAC 24 bit source torrent to MP3 320 (CBR) and MP3 V0 (VBR), then upload to gazelle based trackers.

Features

All gazelle based indexers/trackers are supported

RED
[wip] OPS.

Tested on Linux, theoretically works on Windows.

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

Source Verification

Each source is verified to ensure it's:

A lossless FLAC
Not a scene or lossy release
Files match the torrent hash
Audio tags for artist, album, title and track number are set
[fixed] Vinyl track numbering
Sample rate and channels are supported

Spectrogram Generation

Full and zoomed spectrograms generated for review

Transcoding

[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 directory are included and all other files ignored.
[new] Images larger than 750 KB are (optionally) compressed, converted to JPG and reduced to less than 1920 px.

The logic being that folder and cover images are included but to minimize file size, but for artwork and anything additional the original source can be downloaded

Upload

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

Batch

[new] Verify, transcode and upload from each torrent file in a directory.

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

Getting started

The quickest path to get running is using docker compose, but that will require a little familiarity with docker. But the benefits are reproducability and peace of mind through isolation.

Install

Docker

Build

docker build -t caesura .

docker run \
--user 1000:1000 \
-v ./path/to/your/config.json:/app/config.json \
-v /path/to/your/data:/data \
caesura verify "123456"

Docker Compose

docker compose run caesura verify "123456"

Linux

cargo install imdl

Install FLAC, LAME, SOX and ImageMagick

sudo apt install flac lame sox imagemagick --yes

Install caesura

cargo install caesura

Windows

To be confirmed

For now it's recommended to run with docker.

CLI Commands

Verify source

Verify a FLAC source is suitable for transcoding.

caesura verify [OPTIONS] [SOURCE]

caesura verify --help

Usage: caesura verify [OPTIONS] [SOURCE]

Arguments:
  [SOURCE]
          Source as: torrent id, path to torrent file, or indexer url.
          
          Examples: 4871992, path/to/something.torrent, https://example.com/torrents.php?id=2259978&torrentid=4871992#torrent4871992, or https://example.com/torrents.php?torrentid=4871992

Options:
      --api-key <API_KEY>
          API key

      --indexer <INDEXER>
          ID of the tracker as it appears in the source field of a torrent. Examples: red, pth, ops; Default: red

      --indexer-url <INDEXER_URL>
          URL of the indexer. Examples: https://redacted.ch, https://orpheus.network; Default: Dependent on indexer

      --tracker-url <TRACKER_URL>
          URL of the tracker. Examples: https://flacsfor.me, https://home.opsfet.ch; Default: Dependent on indexer

      --content-directory <CONTENT_DIRECTORY>
          Directory containing torrent content. Typically this is set as the download directory in your torrent client

      --cpus <CPUS>
          Number of cpus to use for processing. Default: Total number of CPUs

      --verbosity <VERBOSITY>
          Level of logs to display. Default: info
          
          [possible values: silent, error, warn, info, debug, trace]

      --config-path <CONFIG_PATH>
          Path to the configuration file. Default: config.json (in current working directory)

      --output <OUTPUT>
          Directory where transcodes and spectrograms will be written

      --target <TARGET>
          Target formats. Default: flac, 320, and v0
          
          [possible values: flac, 320, v0]

      --allow-existing
          Allow transcoding to existing formats

      --skip-hash-check
          Should the torrent hash check of existing files be skipped?

      --hard-link
          Use hard links when copying files

      --compress-images
          Should images greater than 750 KB be compressed?

  -h, --help
          Print help (see a summary with '-h')

Generate spectrograms

Generate spectrograms for each track of a FLAC source.

caesura spectrogram [OPTIONS] [SOURCE]

caesura spectrogram --help

Usage: caesura spectrogram [OPTIONS] [SOURCE]

Arguments:
  [SOURCE]
          Source as: torrent id, path to torrent file, or indexer url.
          
          Examples: 4871992, path/to/something.torrent, https://example.com/torrents.php?id=2259978&torrentid=4871992#torrent4871992, or https://example.com/torrents.php?torrentid=4871992

Options:
      --api-key <API_KEY>
          API key

      --indexer <INDEXER>
          ID of the tracker as it appears in the source field of a torrent. Examples: red, pth, ops; Default: red

      --indexer-url <INDEXER_URL>
          URL of the indexer. Examples: https://redacted.ch, https://orpheus.network; Default: Dependent on indexer

      --tracker-url <TRACKER_URL>
          URL of the tracker. Examples: https://flacsfor.me, https://home.opsfet.ch; Default: Dependent on indexer

      --content-directory <CONTENT_DIRECTORY>
          Directory containing torrent content. Typically this is set as the download directory in your torrent client

      --cpus <CPUS>
          Number of cpus to use for processing. Default: Total number of CPUs

      --verbosity <VERBOSITY>
          Level of logs to display. Default: info
          
          [possible values: silent, error, warn, info, debug, trace]

      --config-path <CONFIG_PATH>
          Path to the configuration file. Default: config.json (in current working directory)

      --output <OUTPUT>
          Directory where transcodes and spectrograms will be written

      --spectrogram-size <SPECTROGRAM_SIZE>
          Output directory to write spectrogram images to
          
          [possible values: full, zoom]

  -h, --help
          Print help (see a summary with '-h')

Transcode FLACs

Transcode each track of a FLAC source to the target formats.

caesura transcode [OPTIONS] [SOURCE]

caesura transcode --help

Usage: caesura transcode [OPTIONS] [SOURCE]

Arguments:
  [SOURCE]
          Source as: torrent id, path to torrent file, or indexer url.
          
          Examples: 4871992, path/to/something.torrent, https://example.com/torrents.php?id=2259978&torrentid=4871992#torrent4871992, or https://example.com/torrents.php?torrentid=4871992

Options:
      --api-key <API_KEY>
          API key

      --indexer <INDEXER>
          ID of the tracker as it appears in the source field of a torrent. Examples: red, pth, ops; Default: red

      --indexer-url <INDEXER_URL>
          URL of the indexer. Examples: https://redacted.ch, https://orpheus.network; Default: Dependent on indexer

      --tracker-url <TRACKER_URL>
          URL of the tracker. Examples: https://flacsfor.me, https://home.opsfet.ch; Default: Dependent on indexer

      --content-directory <CONTENT_DIRECTORY>
          Directory containing torrent content. Typically this is set as the download directory in your torrent client

      --cpus <CPUS>
          Number of cpus to use for processing. Default: Total number of CPUs

      --verbosity <VERBOSITY>
          Level of logs to display. Default: info
          
          [possible values: silent, error, warn, info, debug, trace]

      --config-path <CONFIG_PATH>
          Path to the configuration file. Default: config.json (in current working directory)

      --output <OUTPUT>
          Directory where transcodes and spectrograms will be written

      --target <TARGET>
          Target formats. Default: flac, 320, and v0
          
          [possible values: flac, 320, v0]

      --allow-existing
          Allow transcoding to existing formats

      --skip-hash-check
          Should the torrent hash check of existing files be skipped?

      --hard-link
          Use hard links when copying files

      --compress-images
          Should images greater than 750 KB be compressed?

  -h, --help
          Print help (see a summary with '-h')

Upload

Upload transcodes of a FLAC source.

caesura upload [OPTIONS] [SOURCE]

caesura upload --help

Usage: caesura upload [OPTIONS] [SOURCE]

Arguments:
  [SOURCE]
          Source as: torrent id, path to torrent file, or indexer url.
          
          Examples: 4871992, path/to/something.torrent, https://example.com/torrents.php?id=2259978&torrentid=4871992#torrent4871992, or https://example.com/torrents.php?torrentid=4871992

Options:
      --api-key <API_KEY>
          API key

      --indexer <INDEXER>
          ID of the tracker as it appears in the source field of a torrent. Examples: red, pth, ops; Default: red

      --indexer-url <INDEXER_URL>
          URL of the indexer. Examples: https://redacted.ch, https://orpheus.network; Default: Dependent on indexer

      --tracker-url <TRACKER_URL>
          URL of the tracker. Examples: https://flacsfor.me, https://home.opsfet.ch; Default: Dependent on indexer

      --content-directory <CONTENT_DIRECTORY>
          Directory containing torrent content. Typically this is set as the download directory in your torrent client

      --verbosity <VERBOSITY>
          Level of logs to display. Default: info
          
          [possible values: silent, error, warn, info, debug, trace]

      --config-path <CONFIG_PATH>
          Path to the configuration file. Default: config.json (in current working directory)

      --output <OUTPUT>
          Directory where transcodes and spectrograms will be written

      --target <TARGET>
          Target formats. Default: flac, 320, and v0
          
          [possible values: flac, 320, v0]

      --allow-existing
          Allow transcoding to existing formats

      --copy-transcode-to-content-dir
          Should the transcoded files be copied to the content directory.
          
          This should be enabled if you wish to auto-add to your torrent client.

      --copy-torrent-to <COPY_TORRENT_TO>
          Copy the torrent file to the provided directory.
          
          This should be set if you wish to auto-add to your torrent client.

      --hard-link
          Use hard links when copying files

  -h, --help
          Print help (see a summary with '-h')

Batch

Verify, transcode, and upload from multiple FLAC sources in one command.

caesura upload [OPTIONS] [SOURCE]

caesura upload --help

Usage: caesura batch [OPTIONS] [SOURCE]

Arguments:
[SOURCE]
Source as: path to directory of torrents.

Options:
      --api-key <API_KEY>
          API key

      --indexer <INDEXER>
          ID of the tracker as it appears in the source field of a torrent. Examples: red, pth, ops; Default: red

      --indexer-url <INDEXER_URL>
          URL of the indexer. Examples: https://redacted.ch, https://orpheus.network; Default: Dependent on indexer

      --tracker-url <TRACKER_URL>
          URL of the tracker. Examples: https://flacsfor.me, https://home.opsfet.ch; Default: Dependent on indexer

      --content-directory <CONTENT_DIRECTORY>
          Directory containing torrent content. Typically this is set as the download directory in your torrent client

      --verbosity <VERBOSITY>
          Level of logs to display. Default: info
          
          [possible values: silent, error, warn, info, debug, trace]

      --config-path <CONFIG_PATH>
          Path to the configuration file. Default: config.json (in current working directory)

      --output <OUTPUT>
          Directory where transcodes and spectrograms will be written

      --target <TARGET>
          Target formats. Default: flac, 320, and v0
          
          [possible values: flac, 320, v0]

      --allow-existing
          Allow transcoding to existing formats

      --skip-hash-check
          Should the torrent hash check of existing files be skipped?

      --cpus <CPUS>
          Number of cpus to use for processing. Default: Total number of CPUs

      --spectrogram-size <SPECTROGRAM_SIZE>
          Output directory to write spectrogram images to
          
          [possible values: full, zoom]

      --hard-link
          Use hard links when copying files

      --compress-images
          Should images greater than 750 KB be compressed?

      --png-to-jpg
          Should png images be converted to jpg?
          
          Only applied if the image is greated than 750 KB and `compress_images` is true.

      --no-spectrogram
          Should the spectrogram command be executed?

      --no-upload
          Should the upload command be executed?

-h, --help
Print help (see a summary with '-h')

Configuration

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

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

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

{
    "api_key": "YOUR_API_KEY",
    "output": "path/to/write/output",
    "content_directory": "path/to/your/torrent/content_or_downloads"
}

Full configuration:

{
    "api_key": "YOUR_API_KEY",
    "indexer": "abc",
    "indexer_url": "https://example.com",
    "tracker_url": "https://tracker.example.com",
    "content_directory": "path/to/your/torrent/content_or_downloads",
    "cpus": 6,
    "verbosity": "trace",
    "output": "path/to/write/output",

    "target": ["320", "v0", "flac"],
    "allow_existing": false,
    "skip_hash_check": false,
    "hard_link": false,
    "compress_images": false,
    
    "spectrogram_size": ["full", "zoom"],

    "copy_transcode_to_content_dir": false,
    "copy_torrent_to": "path/to/copy/torrent",
    "hard_link": false,
    
    "source": "123456"
}

Releases and Changes

Release versions follow the Semantic Versioning 2.0.0 specification.

Commit messages follow the Conventional commit specification.

Releases and a full changelog are available via GitHub Releases.

History

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.

Dependencies

~16–31MB
~404K SLoC