generate-changelog

alsdiff

alsdiff is a semantic diff tool for Ableton Live Set (.als) files that makes version control meaningful for music producers.

The Problem

Ableton Live Set files (.als) are gzip-compressed XML. Because standard git diff treats them as binary blobs, using version control to track changes in music projects is nearly impossible.

While existing workarounds allow decompressing .als files to .xml for diffing, the raw output is overwhelmingly verbose. A typical 20-track project can result in a 200,000-line XML file, making generic text diffs unreadable.

alsdiff solves this problem. It decompresses .als files and parses the XML to perform a semantic diff:

• Identity-based matching: Tracks, clips, and devices are matched by their internal IDs, not by position. Renaming or reordering doesn't create false diffs.
• Structured hierarchy: Changes are organized by Live's structure (LiveSet > Tracks > Devices > Parameters).
• Human-readable output: Instead of XML tag changes, you see "Freq: 2500.0 -> 3200.0" or "Notes (3 Added, 1 Removed)".
• Noise filtering: Internal metadata changes (like timestamps or cache data) are ignored by default.

The output of alsdiff looks like this:

* LiveSet
  * Tracks
    * MidiTrack: "Lead Synth"
      * DeviceChain
        + Compressor2
        * Eq8
          * Bands
            * Band.4
              * Freq: 2500.0 -> 3200.0
              * Gain: 0.0 -> 2.5
      * Clips
        * MidiClip: "Verse"
          * Notes (3 Added, 1 Removed)

Installation

Install from pre-built binaries

Download from GitHub Releases:

chmod +x ./alsdiff
mv alsdiff ~/.local/bin  # or any directory in your PATH

Note: The Windows build is currently untested as I don't have access to a Windows machine. Feedback welcome!

Git Integration

A helper script is provided at ./scripts/setup-git.sh. Simply download it to your git repository root and run ./setup-git.sh. This script will automatically configure git to use alsdiff for .als files and optionally install a prepare-commit-msg hook for auto-generating commit messages.

The script provides:

• Automatic .gitattributes configuration for .als files
• Git diff driver setup using alsdiff --git
• Optional prepare-commit-msg hook that auto-generates commit message summaries using alsdiff --mode stats
• Support for all git operations (add, modify, delete, rename, copy)
• Root-only execution guard with clear guidance if run from a subdirectory

Alternatively, you can perform the setup manually.

1. Add to .gitattributes in your repository:

cd /path/to/live_projects/
echo "*.als diff=alsdiff" >> .gitattributes

2. Configure git:

git config --global diff.alsdiff.command "alsdiff <put_extra_args_here> --git"

3. Now git diff will use alsdiff to compare .als files:

git diff HEAD~1 -- your-project.als

Prepare-Commit-Msg Hook

When enabled, the hook automatically prepends change statistics to your commit messages:

$ git commit

MyProject.als:
  Tracks: 1 Added, 3 Modified
  Devices: 2 Added, 5 Removed
  Clips: 4 Added, 2 Modified

# Please enter the commit message...

If the hook runs multiple times for the same commit message (for example during amend/reuse flows), it refreshes the generated stats block instead of duplicating it.

Build from source

# Initialize opam if not done before
opam init

# Create a local switch with the correct OCaml version
opam switch create . --deps-only --with-test

# Activate the environment
eval $(opam env)

# Install dependencies (if not using local switch)
opam install . --deps-only

# Build
dune build

# Run tests (optional)
dune runtest

# Install to ~/.local/bin
dune install alsdiff --prefix ~/.local/

dune exec alsdiff -- file1.als file2.als

Custom build via GitHub Action