Using the library

Basic flow:

  1. Construct a Python dict to contain the album metadata

  2. Construct a bandcrash.options.Options with the encoding and output options

  3. Initialize a concurrent.futures.ThreadPoolExecutor to run the tasks, and a collections.defaultdict(list) to hold its futures

  4. Call bandcrash.process() with the above

API documentation

bandcrash.process(config, album, pool, futures)

Process the album given the parsed config and the loaded album data

Parameters:

  • config (options.Options) – Encoder configuration

  • album (dict) – Album metadata

  • pool (concurrent.Futures.Executor) – The threadpool to submit tasks to

  • futures (dict) – Pending tasks for a particular build phase; should be a collections.defaultdict(list) or similar

Each format has the following phases, each one depending on the previous:

  1. encode: Encodes and tags the output files

  2. build: Builds any extra files (e.g. the web player)

  3. clean: Directory cleanup tasks

And then these two phases are shared across formats but depend on clean (and may run in parallel):

  1. butler: Pushes the build to itch.io via the butler tool

  2. zip: Builds the local .zip file for manual uploading

When this function exits, the futures dict will be fully-populated with a mapping from each phase to a list of concurrent.futures.Future for that phase.

You can wait on each phase’s list separately, or you can collapse it with e.g.:

all_futures = list(itertools.chain(*futures.values()))
concurrent.futures.wait(all_futures)
class bandcrash.options.Options(input_dir: str | None = None, output_dir: str | None = None, num_threads: int = 2, preview_encoder_args: list[str] = <factory>, mp3_encoder_args: list[str] = <factory>, ogg_encoder_args: list[str] = <factory>, flac_encoder_args: list[str] = <factory>, butler_path: str | None = <factory>, butler_args: list[str] = <factory>, do_preview: bool | None = None, do_mp3: bool | None = None, do_ogg: bool | None = None, do_flac: bool | None = None, do_cleanup: bool | None = None, do_zip: bool | None = None, do_butler: bool | None = None, butler_target: str | None = None, butler_prefix: str | None = None)

Encoder options for processing an album.

The following parameters are set by whatever is running the album’s process.

Parameters:

  • input_dir (str) – The working directory for the input specification

  • output_dir (str) – The output directory to store the various builds

  • butler_path (str) – The path to the itch.io Butler tool. By default, searches for butler in the user’s PATH.

  • butler_args (str) – Extra arguments to give to the butler tool (e.g. upload version, --identity, etc.)

  • preview_encoder_args (list) – FFmpeg encoder options for the web player

  • mp3_encoder_args (list) – FFmpeg encoder options for the album download

  • ogg_encoder_args (list) – FFmpeg encoder options for the Ogg album download

  • flac_encoder_args (list) – FFmpeg encoder options for the FLAC album download

The following parameters are set by the album’s specification data, but may be overridden by the process runner (e.g. via command line arguments). A value of None indicates that it should use the album’s configuration; defaults listed here are what occurs if it is unset both here and in the album specification. If unset, all of them default to True unless otherwise specified.

Parameters:

  • do_preview (bool) – Whether to build the web preview

  • do_mp3 (bool) – Whether to build the MP3 album download

  • do_ogg (bool) – Whether to build the Ogg album download

  • do_flac (bool) – Whether to build the FLAC album download

  • do_cleanup (bool) – Whether to clean up extra files from the target directories

  • do_zip (bool) – Whether to build a .zip archive

  • do_butler (bool) – Whether to automatically upload builds to itch.io via Butler

  • butler_target (str) – The Butler target for the upload (e.g. fluffy/novembeat-2022 for https://fluffy.itch.io/novembeat-2022)

  • butler_prefix (str) – A prefix to add to the Butler channel name; used for variations (e.g. bob- gives channel names of bob-mp3, bob-flac, etc.)