atm-cli: Generating MIDI Melodies from the Command Line

Why atm-cli targets combinatorial MIDI generation

atm-cli addresses a specific data-generation problem: creating MIDI files from combinations of musical notes, potentially across very large collections. The README says the tool was purpose-built for All the Music, LLC and tailored to an effort to generate billions of melodies by brute force. That context explains its design. It is not presented as an interactive MIDI editor, a notation application, or a general composition assistant. Its users are people who need deterministic command line output from note sequences, especially people preparing datasets for music-related experimentation.

The central input is a comma-separated pitch sequence using forms such as `C:4` and `A:4`. The tool can turn that sequence into a single MIDI file, or use a pool of notes and a requested length to generate a range of melodies. The latter mode is the more distinctive feature. It is aimed at bulk output, where the volume and organization of files matter as much as the MIDI content itself.

The project is not archived, and the last push was on 2026-05-29. The repository has no GitHub releases, so the version visible in `Cargo.toml` is the clearest package version statement available: `0.3.0`. The README identifies `libatm` as the underlying library dependency for MIDI generation and manipulation.

The `gen` and `partition` command flow

The CLI is organized around named subcommands. The usage text lists `estimate`, `gen`, `partition`, and `help`. `gen` creates MIDI files and stores them in one file or multiple files. `partition` calculates the directory or partition location for a pitch sequence under a chosen partitioning scheme. This separation makes the storage model explicit: generation produces output, while `partition` helps locate a specific melody later.

The README documents `gen single` for a direct conversion from a melody to `test.mid`. Its `gen *` family handles bulk generation. The `gen tar-gz` example combines generation with Gzip compression and Tar packaging. The README states that the generated archive uses a directory structure with no more than 4,096 files per directory. That constraint is relevant for anyone planning storage or extraction workflows.

The project also includes `estimate`, described in the command summary as a way to estimate output size for storage backends. The repository dependencies indicate the implementation uses `tar`, `flate2`, `humansize`, `itertools`, `structopt`, `libatm`, `pbr`, and `thiserror`. Those dependencies support archive creation, compressed output, command parsing, error handling, and reusable MIDI operations. The exact internal partitioning algorithm is not documented in the README, so the directory mapping should be checked against the crate documentation before relying on it for an automated retrieval system.

Building atm-cli from the repository

$ git clone https://github.com/allthemusicllc/atm-cli.git
$ cd atm-cli
$ git submodule update --init
$ cargo build --release
$ cargo run --release -- -h # show usage

The final command should print the command summary shown in the README. A successful installation therefore means both a completed release build and a working `atm` command. The README does not document installation through a package registry or an operating-system package manager.

Generating a first MIDI file

atm gen single 'C:4,D:4,E:4,F:4,G:4,A:4,B:4,C:5' test.mid

The note syntax uses pitch names, octaves, commas, and colon-separated values. The output filename is supplied directly as the final argument. The README does not show an alternative output format for this directive, so `test.mid` is the first result to check for after running the command.

Creating partitioned Tar.gz melody datasets

atm gen tar-gz -p 2 'C:4,D:4,E:4,F:4,G:4,A:4,B:4,C:5' 8 C4_D4_E4_F4_G4_A4_B4_C5.tar

The storage-oriented output is designed for repeated generation, but the README does not specify the number of generated files for this example. It also does not document archive extraction commands or progress output. The archive name and directory limit should be verified directly in the generated output before integrating the command into a batch workflow.

Locating a melody with partition output

atm partition -p 2 'C:4,C:4,C:4,C:4,C:4,C:4,C:4,C:5'

This command does not appear to generate another melody. Its purpose is to calculate the partition location. That distinction matters when comparing a single-file workflow with archive generation: the output filename and partition depth are separate concerns in the documented interface.

Storage trade-offs and limitations of the CLI

The main limitation is scope. atm-cli is a command line generator tailored to brute-force melody datasets, not a general MIDI manipulation interface. The README refers users who need a Rust library for generating and working with MIDI files to `libatm`. Choosing the CLI when a library is needed adds an output format and process boundary that the project does not document as a separate integration feature.

Bulk generation also creates an operational concern. The project is designed to produce many files and can package them into an archive, but the README does not document streaming behaviour, progress reporting, cancellation, retry semantics, duplicate handling, or recovery after an interrupted run. It also does not establish how storage requirements scale for a particular note pool and melody length. The `estimate` subcommand exists for storage planning, but the README does not show its syntax or output format.

The partitioning depth is another deliberate constraint. A depth of 2 changes the output location, while omission defaults to depth 1. Users who assume that the same depth will be used for every archive could have trouble locating files. The documented example gives the required lookup command, but not the full mapping rules. The crate documentation is the appropriate place to inspect that behavior before automating it.

License, maintenance, and upgrade considerations

The README says the code is freely available under the Creative Commons Attribution 4.0 International License, identified as `CC BY 4.0`. It explains that this permits copying, redistribution, remixing, transformation, and commercial use, while requiring attribution and preventing additional restrictions on derivative works. The repository metadata also classifies the license as a custom license that GitHub cannot classify and points to the `LICENSE` file. That discrepancy is worth checking directly before redistribution or integration. The README's licensing explanation is not a substitute for reviewing the repository's actual license text.

The last push was on 2026-05-29, so the repository is not described as archived and its recorded development activity is recent relative to the available record. However, there are no GitHub releases, and the README does not document a release schedule or upgrade policy. Users should treat `Cargo.lock` and the checked-out dependency sources as part of the build environment when reproducing results. The local `lib/libatm` dependency also means changes in that submodule can affect the CLI build, so submodule revisions should be recorded alongside generated datasets.

Existing datasets are available through the All the Music archive URL listed in the README. That is separate from installing the CLI and does not establish that the archive contains every output mode or configuration supported by the current source.

Choosing atm-cli versus libatm

The clearest alternative named by the project is `libatm`. The README says to use `libatm` when the need is specifically a Rust library for generating and working with MIDI files. `atm-cli` places a command line workflow around the library, adds storage-oriented generation directives, provides partition calculations, and packages output for dataset workflows. `libatm` is the more direct choice for code that needs MIDI operations inside a Rust application, while `atm-cli` is more appropriate for shell scripts, scheduled dataset jobs, or operators who want file-based output without writing Rust glue code.

A standard DAW or editor would serve a different purpose, but the README does not compare atm-cli with those tools, so the project-specific distinction should remain focused on documented behavior. atm-cli does not present itself as a replacement for composition software. Its adoption case is automated generation and organization of note-sequence MIDI files.

Editorial conclusion

Adopt atm-cli when repeated, combinatorial MIDI generation and filesystem partitioning are the primary requirements. Do not treat it as a replacement for a Rust library or a DAW. Before adoption, inspect the LICENSE file, confirm the intended storage layout, and verify that the generated pitch syntax and partition depth match your dataset requirements.

Frequently asked questions

Official sources

1. allthemusicllc/atm-cli on GitHub
2. Issues
3. Project website
4. README