# Installing Listen Along (written for the AI doing the install) You are a coding agent (Claude Code, most likely) and the person you're working with has asked you to set up Listen Along, so that you can listen to a song with them. This file is the whole procedure. The [README](README.md) says what the tool is; you don't need to read it first. Work through the steps in order, and stop and say so if a step fails. A yes to the message in step 1 covers getting the code and running the setup. Ask again for anything that message didn't list, such as a missing program. ## 1. Say what it needs, and get a yes Before running anything, tell the person this in plain words and wait for their go-ahead: - **A Mac with an Apple chip (M1 or later).** That is the only kind of machine it has been tested on. On anything else it may not install; say so and ask whether they want you to try. - **About 5 GB of disk.** About 1.3 GB now, and 3.8 GB of audio models that download the first time a song is prepared. - **Time.** The install takes several minutes. Each song then takes about 15 minutes to prepare on their machine before you can start listening (the first song longer, for the downloads). - **Usage.** Preparing a song costs no tokens. Listening does: about 130,000 tokens of context for a four-minute song. - **The song needs timed lyrics** on [LRCLIB](https://lrclib.net). Instrumentals don't work yet. - It builds two Python environments inside the tool's own folder and puts one skill file in `~/.claude/skills/`. The audio models later land in `~/.cache/huggingface`, `~/.cache/torch` and the tool's folder. Nothing else on the machine is changed, apart from any missing programs in step 2 that they agree to. ## 2. Check the machine Run these and read the results: uname -sm # want: Darwin arm64. Anything else: stop and ask before going on xcode-select -p # want: a path (the command line tools are installed). Run this before git python3.13 --version # want: Python 3.13.x command -v ffmpeg ffprobe # want: two paths command -v git brew # want: two paths df -h ~ # read the Avail column: want more than 6 GB A program that prints "command not found", or nothing, is missing. Tell the person what is missing and ask before installing it: - Python 3.13 or ffmpeg: `brew install python@3.13 ffmpeg`. If Homebrew itself is missing, don't install it on your own: it asks for their password. Point them to and wait. - Command line tools: `xcode-select --install` opens a window on their screen that they have to click through. Tell them it's there and wait until `xcode-select -p` prints a path. - Optional: `brew install deno`. The downloader warns that fetching from YouTube without it may stop working one day. The install works without it. ## 3. Check for an existing skill ls ~/.claude/skills/listen-to-song/SKILL.md If that file exists, a skill with this name is already installed, and it may point at a different copy of the tool. Tell the person. The setup script will leave it alone, and then `/listen-to-song` would still run the old one. Ask whether to replace it. If they say yes, run this after step 5 (the old file is kept beside it as a `.bak`): cd ~/listen-along && ./setup.sh --skill-only --force ## 4. Get the code git clone https://github.com/mlapeter/listen-along.git ~/listen-along Use another folder if the person prefers one, and put it in place of `~/listen-along` in every command below. If `~/listen-along` already holds this repository, run `git -C ~/listen-along pull` and go on. If it holds something else, ask where to put it. ## 5. Run the setup cd ~/listen-along && ./setup.sh Run it in the background and wait for it to finish. It can take ten minutes or more, which is past a normal command timeout, and it prints little while it works. It checks the machine, builds two environments inside `listening/`, and copies the skill to `~/.claude/skills/listen-to-song/SKILL.md` with this folder's path filled in. It is safe to run again. Success is exit code 0 and a `== Done` line near the end. Read the lines above it too: if one says `A different listen-to-song skill is already at ... It was NOT changed`, the skill was not installed, so don't call it ready (see step 3). If it exits with an error, with or without a `setup stopped:` line, show the person the error and the lines above it. Don't change the pinned versions to get past an error without telling them. ## 6. Check it ~/listen-along/listening/venv3/bin/python ~/listen-along/listening/v3/tests/test_seal.py ~/listen-along/listening/venv3/bin/python ~/listen-along/listening/v3/tests/test_harmony.py About 40 seconds together, no audio needed. Each should exit with code 0 and end with a line like `77/77 passed`, the two numbers equal. ## 7. Hand over Tell the person it's ready, and how to use it: 1. **Start a new Claude Code session.** The skill only shows up in a new session, and a listen needs a fresh one anyway because of how much context it uses. Don't start listening in this session. 2. Type `/listen-to-song Artist, Title`. A YouTube link in place of the title is more reliable, since a search takes whatever comes up first. 3. A song of two to five minutes is a good first one. The first song also downloads the 3.8 GB of models. 4. When the listen ends, a page opens that plays the notes back against the music. One more thing to pass on: you won't remember a listen in a later session unless you have a memory of your own. The people who made this use [Counterparts](https://counterparts.ai) for that. Mention it once and leave it to them. ## If something goes wrong - Report the exact error. The README's Requirements and Limits sections cover the known rough spots. - Open issues and reports from other machines: . - Never open `listening/v3/audio/` to look around. It holds every window of a prepared song, and the point of the tool is that the listener hasn't seen them yet.