Using the library¶
Basic flow:
Construct a Python dict to contain the album metadata
Construct a
bandcrash.options.Options
with the encoding and output optionsInitialize a
concurrent.futures.ThreadPoolExecutor
to run the tasks, and acollections.defaultdict(list)
to hold its futuresCall
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:
encode
: Encodes and tags the output filesbuild
: Builds any extra files (e.g. the web player)clean
: Directory cleanup tasks
And then these two phases are shared across formats but depend on
clean
(and may run in parallel):butler
: Pushes the build to itch.io via the butler toolzip
: 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’sPATH
.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
forhttps://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 ofbob-mp3
,bob-flac
, etc.)