When you transcribe, your hands are on an instrument — not on a mouse. Artscripture is built around that: every operation has a key, the window is one uninterrupted waveform, and the passage you are working on stays where you put it.

Status: in development, and playable. Load a file, hear it, select, loop, change speed — all from the keyboard. Not yet built: spectrum analysis, MIDI input, and stem separation (researched in depth, deliberately not started).

make bootstrap
make app && open .build/xcode/Build/Products/Release/Artscripture.app

Or grab a signed, notarised build from Releases.

Artscripture is not the only option, and for many people it should not be the first one tried.

• Transcribe! (Seventh String) — the long-standing standard, and genuinely excellent: deep, fast, thoroughly documented, actively maintained, and cross-platform. Its feature set still goes well beyond this project's. The interface simply feels of an earlier era, and that — not the engineering — is what Artscripture reacts to. If you want a mature, supported, commercially backed tool today, buy it; it is inexpensive and very good.
• Amazing Slow Downer — a focused, reliable slow-down-and-loop player, on desktop and mobile.
• Anytune — macOS and iOS, strong on practice tooling.
• A full DAW (Logic, Ableton, Reaper) — if you already live in one, it will slow audio down and loop it perfectly well. It is simply a lot of software to open to learn eight bars.

There are three ways in, and they are for different people.

Grab the newest Artscripture-<version>.zip from Releases, unzip it, and drag Artscripture.app to /Applications.

macOS 26 on Apple Silicon. Homebrew ships arm64-only libraries and this has never been an Intel product, so the bundle is arm64 rather than universal.

If macOS says the app "cannot be opened" the build was not notarised. Right-click it ▸ Open and confirm, or xattr -d com.apple.quarantine Artscripture.app. See Signing for why, and for what makes it stop happening.

make app
open .build/xcode/Build/Products/Release/Artscripture.app

That produces Artscripture.app: a real, double-clickable bundle with an icon, a version, and a bundle identifier. Drag it to /Applications or ~/Applications and it behaves like any other Mac app — it appears in Finder's Open With for every format it decodes, and a file dropped on its dock icon opens in it.

make dist wraps the signed bundle in dist/Artscripture-<version>.zip for handing to somebody else.

project.yml is the source of truth for the bundle. The Artscripture.xcodeproj that XcodeGen generates from it is disposable and gitignored — never edit or commit it. The app icon is likewise generated, from App/GenerateIcon.swift.

swift run -c release ArtscribeApp

No Xcode project, no bundle, no signing. Every module except the app shell also builds and tests headlessly under swift test. Bundling is an additional path, not a replacement: make check never touches Xcode.

Release, not debug — a debug build decodes roughly four times slower.

An unbundled swift run binary is not an app bundle, so macOS starts it as an accessory. The app asks for the regular activation policy at startup to get its menu bar and keyboard focus back. It also never receives Launch Services open events, so "Open With" and dock drops only work from the bundle.

Artscripture has two time-stretching backends, and which one is running is not a user-facing choice. It is one for whoever is working on the audio:

ARTSCRIBE_DEV_MENU=1 swift run -c release ArtscribeApp

That adds Playback ▸ Developer ▸ Stretch Engine: Rubber Band R3 (Studio), Rubber Band R2 (Fast), Signalsmith, Signalsmith (Cheaper). Switching rebuilds the audio graph, so you will hear a short gap — you are comparing two renders separated by a reload, not crossfading between them.

An environment variable rather than a DEBUG-only build, deliberately: the menu exists to judge engines by ear, and a debug build decodes about four times slower, so it would make both engines sound bad and the comparison worthless. The gate has to survive -c release.

A bundle launched from Finder inherits no shell environment and so never shows it, which is the point — the menu cannot appear for someone who did not ask for it from a terminal.

For a headless A/B, with the render-thread degradation counters a menu cannot show you:

swift run -c release artscribe-cli --engine signalsmith track.flac 0.5 10 14

make ios-test              # or: make ios-test SIM='iPad Pro 13-inch (M4)'

248 tests — everything portable, which is all of ArtscribeKit, Waveform, TimeStretch and Playback except the suites that need Rubber Band. Those are behind #if canImport(CRubberBand) and simply do not exist on iOS.

make ios-check only compiles for iOS. This runs, which is a different claim: Signalsmith is the only stretcher on iOS, so its loop-seam proof belongs on the platform that uses it.

--engine takes studio, fast, signalsmith or signalsmithCheaper, and the chosen engine is printed on every run — listening to the wrong one without knowing is the mistake the tool exists to prevent.

make ipad              # build, install, launch with the console attached
make ipad DEV=1        # …and with Playback ▸ Developer ▸ Stretch Engine
make ipad-container    # pull the app's UserDefaults and sidecars off the device

--console keeps the process attached and streams its output. That is the only channel that reaches the terminal — this macOS's log stream has no --device-name, and devicectl's --log-output logs the tool rather than the app — so anything you want to see from a device run has to be printed by the app itself. Ctrl-C detaches the console without killing the app.

make ipad-container is the one that earns its keep. The Open Recent bookmark bug was diagnosed by reading the stored preferences: the bookmark keys and the recent-file paths disagreed by exactly the /private prefix, which no amount of reading the code would have revealed.

There is an iPad target — ArtscribeiPad — and it needs no App Store, no TestFlight and no review to get onto your own device: open a track, draw the waveform, select, loop, play and change speed. Speed works because the stretcher is pluggable and iPadOS gets Signalsmith Stretch, MIT and compiled from vendored source — there is no Homebrew on a phone. See PlatformStretcher.

The one behavioural difference is decoding: Ogg Vorbis does not open on iPadOS.

Once, on the iPad: Settings ▸ Privacy & Security ▸ Developer Mode ▸ on, then restart. (iOS 17 or newer; devicectl does not support older devices.)

Once, on the Mac: export ARTSCRIBE_TEAM_ID — the same one signing already uses. Device builds are signed automatically with an Apple Development certificate, which Xcode mints from your account; this is not the Developer ID path the Mac release uses.

Connect the iPad by USB and find its identifier:

xcrun devicectl list devices

The column you want is Identifier — a UUID like 00008103-000A1B2C3D4E5F00, not the device name and not the serial number. If nothing is listed, the iPad is locked, has never trusted this Mac (unlock it and answer Trust), or Developer Mode is still off.

Then build, install and launch:

xcodegen generate                       # regenerate the project; it is gitignored
xcodebuild build -scheme ArtscribeiPad -destination 'id=<identifier>' \
    -derivedDataPath .build/xcode-ipad

xcrun devicectl device install app --device <identifier> \
    .build/xcode-ipad/Build/Products/Debug-iphoneos/Artscripture.app

xcrun devicectl device process launch --device <identifier> com.artscribe.Artscripture

To iterate without a device, build for a simulator instead — no signing, no team:

xcodebuild build -scheme ArtscribeiPad \
    -destination 'platform=iOS Simulator,name=iPad (A16)' CODE_SIGNING_ALLOWED=NO

The provisioning profile lasts a year with a paid Apple Developer membership, and seven days with a free Apple ID — after which the app stops launching until you reinstall it.

Artscripture links Rubber Band and, through it, libsamplerate. Both come from Homebrew at build time, and make app copies them into Artscripture.app/Contents/Frameworks and repoints the binary's load commands at @rpath, so the finished bundle does not need Homebrew on the machine that runs it. The build fails rather than shipping a bundle that still references anything outside itself — see App/embed-dependencies.sh.

Their licences travel with them, in Contents/Resources alongside Artscripture's own.

Apple Silicon only. Homebrew ships arm64-only libraries and the project has never been an Intel product, so the bundle is built arm64 rather than universal.

security find-identity -v -p codesigning
# 1) A1B2C3... "Developer ID Application: Your Name (TEAMID)"

export ARTSCRIBE_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)"
export ARTSCRIBE_TEAM_ID=TEAMID
export ARTSCRIBE_HARDENED_RUNTIME=YES

make dist        # signs with the real identity, hardened runtime on

xcrun notarytool store-credentials artscribe-notary \
    --apple-id [email protected] --team-id TEAMID --password <app-specific-password>

make notarize    # submits, waits, staples, re-zips, and runs spctl

status: Accepted                       ← Apple's verdict
The staple and validate action worked  ← the ticket is now inside the .app
accepted (source=Notarized Developer ID)  ← what Gatekeeper tells the recipient

xattr -w com.apple.quarantine "0081;$(printf %x $(date +%s));Safari;" Artscripture.app
spctl --assess --type execute --verbose=4 Artscripture.app   # must still say: accepted

git tag -a v0.1.0 -m "Artscripture 0.1.0" && git push origin v0.1.0

mkdir -p ~/.private_keys && chmod 600 ~/.private_keys/AuthKey_XXXXXXXXXX.p8

export ARTSCRIBE_ASC_ISSUER_ID="…"   # the UUID at the top of the Integrations page
export ARTSCRIBE_ASC_KEY_ID="…"      # the 10-character key ID
export ARTSCRIBE_ASC_KEY_PATH="$HOME/.private_keys/AuthKey_XXXXXXXXXX.p8"

make asc-check   # are the credentials present? fails by name, not obliquely
make archive     # → .build/xcode-archive/Artscripture.xcarchive
make upload      # exports a signed .ipa and sends it to App Store Connect

Slowing audio down without changing pitch is the hard part, and it is the reason this project exists at all. Artscripture uses Rubber Band 4.0's R3 "Finer" engine — a multiresolution, phase-locked spectral stretcher in the same class as Ableton's Complex Pro.

Measured pitch error, FFT peak against a reference tone:

Studio is the default and earns it. Fast exists for low-CPU scrubbing and trades pitch accuracy for speed — it is not a pitch reference, especially above 1×.

Looping is sample-accurate and feeds the stretcher continuously across the seam rather than resetting it. That detail is the difference between a clean loop and a click on every repetition: forcing a reset at the boundary produces a 28× discontinuity against the signal's natural step size.

Release, not debug — a debug build decodes roughly four times slower.

Drop a file on the window, press ⌘O, or pick one from the recent list on the resting screen — the five most recent, named by file and folder so two rips of the same track are told apart. On iPad that list is the only route to recents, since there is no menu bar to hang Open Recent from.

Recents survive a relaunch on both platforms. On iPad that needs a security-scoped bookmark, because a file picked out of Files lives outside the app's container and its URL stops being readable when the app restarts.

Preroll. You stop on a note; to hear it in context you have to start slightly before it. Space therefore resumes from position − preroll rather than from exactly where it stopped. Two seconds by default, editable in Settings ▸ Playback in seconds with fractions, and 0 turns it off — that is an allowed value, not a rejected one. It clamps at the start of the file, and when a loop is active and the playhead is inside it, at the loop's in point, so a resume never steps outside the passage you set. Pausing and resuming twice rolls back twice: each press is a fresh resume, which is how you inch back through a phrase. ⇧Space never prerolls.

H turns it off and on again. That is not the same as setting it to 0: zero is a permanent "resume exactly where I stopped", whereas the toggle is the mode you flip while working and it remembers your seconds. It is also a Playback menu item and a transport-bar button beside the loop, both of which show the current state.

Drag in the lanes to select, shift-drag to extend, click to place the playhead, double-click to place it and play from there (⌘A is still Select All). Pinch to zoom, two-finger scroll to pan. Dragging the overview strip moves the visible window. Drag down on the time ruler — or ⌥-drag in the waveform — to zoom in smoothly; Settings ▸ Playback ▸ Invert zoom direction reverses that and the scroll wheel together.

Press ⌘P — or View ▸ Practice — for a separate window that plays your loop over and over while the speed climbs, so you can take a passage from slow to tempo without touching anything.

Give it three numbers and it works out the rest:

• Start speed, end speed and number of repetitions. The default is 50% → 100% over ten passes; the per-repetition step is computed and shown under the fields. Both endpoints are played, so ten repetitions from 50% to 100% is nine steps of 5.6%, not ten.
• An end speed below the start speed ramps down, which is a real way to practise — you take something you can just about play at tempo and slow it down to hear what your fingers are actually doing.
• Start speed equal to end speed drills one tempo for a set number of passes.

While it runs the window shows which repetition you are on, the speed you are hearing, and how many are left. It advances when the loop comes round, not on a timer — a timer would drift the moment the loop length or the speed changed underneath it, and the ramp changes the speed on purpose.

When the last repetition finishes the ramp holds the final speed and keeps playing. It does not stop you: a ramp is a speed automation, not a transport, and the end of one is the moment you have arrived at the passage, at tempo, in the loop — which is what the whole exercise was for. The window says Ramp complete — holding 100% so it is not a silent ending.

A ramp needs a loop. With none set, the window says so and names the keys that fix it (A and S, or G from a selection) rather than offering a Start button that would do nothing. Starting a ramp switches looping on for you if the region is set but disabled.

Like the shortcut window it is a separate window rather than a panel, and for a sharper reason: this is a thing you watch the waveform while using, so it must cost the waveform no width.

Press ⌘/ — or View ▸ Keyboard Shortcuts — for a separate window with the whole keymap drawn on a keyboard, and a searchable list beside it.

• The keyboard shows one modifier layer at a time, and follows the modifiers you hold. Hold ⇧ and A S D F change from setting the loop's edges to moving them; add ⌥ and they move further. Six actions live on the A and Z caps alone, which is why a picture that stacked them all would teach nothing. Layers are derived from the bindings that exist, so a new chord gets a layer without anyone maintaining a list.
• A layer can also be pinned from the picker, for anyone who cannot hold two modifiers at once. Holding wins while you hold; the pin is what you come back to.
• One filter narrows both surfaces. Type "loop" and the list shows the loop actions while every key that is not one goes quiet. It matches the action's name, its group, its note, and the chord both written (⌥⇧A) and spoken ("option shift").
• Keys are tinted by category and unbound keys are dimmed. Actions with no shortcut at all — Stop, Clear Loop, the two Scroll items — still appear in the list.

Drag the divider between the keyboard and the list to resplit it; it stays where you left it between launches. The window is separate rather than a panel inside the document on purpose: a panel can only exist by taking width from the waveform.

It is generated from the same ActionCatalog the menus and the keyboard are built from, so it cannot fall out of step with what the keys actually do — see Sources/ArtscribeUI/ ActionCatalog.swift, and ActionCatalogTests for the test that enforces it.

Every shortcut above also appears beside its item in the menus — selection in Edit, looping in Loop, the transport, speed, volume and output device in Playback.

Everything is decoded natively by macOS — no ffmpeg, no bundled codecs: MP3, AAC, M4A/MP4, ALAC, FLAC (including 24-bit), WAV, AIFF, CAF, Ogg Vorbis, and Opus.

Requires macOS 26+, Xcode 26+ (Swift 6.3), and Apple Silicon.

make bootstrap   # brew: rubberband, swiftlint, xcodegen, pre-commit (+ installs hooks)
make check       # format check, lint, and the full test suite — the gate for every commit
make app         # the double-clickable Artscripture.app
make dist        # a zip of the signed bundle

Every module except the app shell builds and tests headlessly under swift test — no Xcode project, no scheme, no audio hardware. See Running Artscripture above for which path to use when.

Integration tests read $ARTSCRIBE_TEST_MEDIA_DIR and skip cleanly when it is unset, so CI stays green without it. Point it at a directory of real music to exercise the decode, waveform and playback paths at full scale:

ARTSCRIBE_TEST_MEDIA_DIR=~/Music/SomeAlbum swift test -c release

Measure performance in release. A debug build is roughly 4× slower and will mislead you.

Known issue: the full suite hangs when $ARTSCRIBE_TEST_MEDIA_DIR is set. make check is unaffected. Being tracked.

make check tests the modules headlessly. The other half is ArtscribeAcceptance, a separate executable that opens a real window and drives it through about six hundred checks with genuine NSEvents — menus, key equivalents, pointer drags and real playback.

swift run -c release ArtscribeAcceptance --list
swift run -c release ArtscribeAcceptance --acceptance <audio-file> --only loop

--list names the sixteen groups it is split into. --only and --skip take comma-separated names, and --quick drops the two groups that wait on timed playback. A single group takes seconds where the full run takes minutes — but a run that skipped anything says so in its summary and exits 2 rather than 0, because a partial acceptance run is not an acceptance pass.

The harness never makes a sound: it closes a process-wide audibility gate in the audio graph itself, before any output can exist. ARTSCRIBE_ACCEPTANCE_AUDIBLE=1 is the deliberate override.

Nine SwiftPM modules across three execution contexts. Dependencies point one way only.

BACKGROUND (load)       MAIN ACTOR (model & UI)     RENDER THREAD (real-time)
AudioDecode             ArtscribeUI                 AVAudioSourceNode
    ↓                        ↓                          ↓
DecodedAudio  ─────────► ArtscribeKit               PlaybackEngine
    ↓                        ↓                          ↓
Waveform      ─────────► ArtscribeApp               TimeStretch (Rubber Band)

ArtscribeKit imports nothing — not even Foundation. The main actor and the render thread communicate through exactly one boundary: a lock-free SPSC command ring going down, and atomics the UI polls going up. The audio thread never allocates, never locks, never calls back, and never touches the model.

Design documents live in docs/superpowers/specs/ and docs/superpowers/plans/; CLAUDE.md carries the working conventions.

Artscripture's own source is Apache-2.0. See LICENSE and NOTICE.

A distributed binary may be a different matter, and which one depends on what it links. The GPL binds the combined work at the moment it is distributed, not the repository:

Rubber Band is the best open time-stretching engine available and quality at low speeds is the whole point of the product, so the macOS build takes that trade deliberately. Its "or later" clause is what makes the arrangement legal at all — Apache-2.0 is compatible with GPLv3 and not with GPLv2, so the combination is taken as v3.

docs/LICENSING.md has the full reasoning, including what changes when a permissively-licensed backend lands.