Lionel’s Music Analyzer: User Guide

Turn a folder of music into a searchable catalogue, then find, preview and pitch the right track in seconds.

What it does

Music Analyzer listens to a folder of tracks and writes an Excel report with one row per track. Each row has the genre, style, instruments, vocals, moods, tempo, key, energy, a written description, search keywords and suggested placements, which is everything a music supervisor asks about.

The second half of the app, Search Library, reads those reports so you can find a track by describing it (“sad piano, slow build”), listen to it, and build a pitch list.

How it works, in plain English

  1. Your file tags (genre, BPM, composer) are the starting point.
  2. The app measures the audio on your computer: tempo, key, loudness, brightness and rhythm.
  3. A built-in listening model (it runs locally) spots instruments, vocals, style and mood.
  4. Optional: Claude turns those facts into a clear description, mood words and keywords.
Your audio never leaves your computer.Only text facts (tags, measurements, instrument guesses) are ever sent to Claude, and only if you turn it on.

Installing

You only do this once. The installer sets everything up in its own private folder, so it will not interfere with anything else on your computer.

What you needA Mac or Windows PC, an internet connection, about 3 GB of free disk space, and about 15 minutes. Python 3.12 from python.org is required. If you don’t have it, the installer tells you and shows the link.

The download

Unzip the download into a folder. It contains these files, which must stay together while you install:

  • music_analyzer_app.py (the program)
  • requirements.txt (the list of parts to install)
  • Install.command and Uninstall.command (Mac)
  • Install-Windows.bat and Uninstall-Windows.bat (Windows)

On a Mac

  1. Install Python 3.12 if you haven’t already: python.org/downloads/. Open the installer and click through to the end.
  2. Right-click Install.command and choose Open, then click Open again. (Right-click is only needed the first time, to get past the macOS safety check.)
  3. Wait. A Terminal window shows progress. The big step can take 5 to 15 minutes, and it is fine if it looks quiet for a while.
  4. Done. When you see SUCCESS, Lionel’s Music Analyzer is on your Desktop. Double-click it. You can drag it to the Dock or the Applications folder.

On Windows

  1. Install Python 3.12 if you haven’t already: python.org/downloads/. In the installer, tick Add python.exe to PATH and leave tcl/tk and IDLE ticked. (The Microsoft Store version of Python won’t work.)
  2. Double-click Install-Windows.bat. If Windows says “Windows protected your PC”, click More info, then Run anyway.
  3. Wait. A black window shows progress. The big step can take 5 to 15 minutes.
  4. Done. When you see SUCCESS, the app opens by itself, and a Lionel’s Music Analyzer shortcut is on your Desktop and in the Start menu.
The first analysis downloads the listening model.The very first time you analyze music, the app downloads its audio model (about 350 MB). After that it works offline, except for the optional Claude step. Lyrics download an extra speech model the first time you use them.

Updating

When you get a new music_analyzer_app.py, put it in the install folder (replacing the old one) and run the installer again. It is fast the second time, and your settings, reports, shortlist and saved results are kept.

Uninstalling

Run Uninstall.command (Mac) or Uninstall-Windows.bat (Windows). It removes the app and its private folder. It asks before deleting your saved settings and, on a Mac, your saved API key. Your Excel reports are never touched.

Backup plan: install with Terminal

If the installer won’t open or stops with an error, the same steps can be done by hand. Nothing here is risky: it only creates the private folder .music_analyzer in your home folder.

Mac: open Terminal (press ⌘ Space, type Terminal, press Return). Type cd (with a space after it), drag the unzipped folder into the Terminal window, and press Return. Then try the installer from there:

chmod +x Install.command
./Install.command

If that still doesn’t work, run the steps one at a time. Paste each block and wait for it to finish before the next:

python3.12 -m venv ~/.music_analyzer/venv
~/.music_analyzer/venv/bin/python -m pip install --upgrade pip wheel "setuptools<81"
~/.music_analyzer/venv/bin/python -m pip install numpy==1.26.4 scipy==1.11.4 soundfile==0.12.1 librosa==0.10.1
~/.music_analyzer/venv/bin/python -m pip install -r requirements.txt
~/.music_analyzer/venv/bin/python music_analyzer_app.py --install-app

Windows: open the folder in File Explorer, click the address bar, type cmd and press Enter. A black window opens in the right place. Try the installer from there:

Install-Windows.bat

If that still doesn’t work, run the steps one at a time:

py -3.12 -m venv %USERPROFILE%\.music_analyzer\venv
%USERPROFILE%\.music_analyzer\venv\Scripts\python -m pip install --upgrade pip wheel "setuptools<81"
%USERPROFILE%\.music_analyzer\venv\Scripts\python -m pip install numpy==1.26.4 scipy==1.11.4 soundfile==0.12.1 librosa==0.10.1
%USERPROFILE%\.music_analyzer\venv\Scripts\python -m pip install -r requirements.txt
%USERPROFILE%\.music_analyzer\venv\Scripts\python music_analyzer_app.py

Check that everything is installed

In Terminal (Mac) or the black window (Windows), run the checker using the private environment’s Python:

# Mac
~/.music_analyzer/venv/bin/python music_analyzer_app.py --doctor

# Windows
%USERPROFILE%\.music_analyzer\venv\Scripts\python music_analyzer_app.py --doctor

It prints a short checklist and says exactly what is missing and how to fix it.

Quick start

  1. Choose Music Folders. Pick one or more folders of audio (MP3, WAV, FLAC, M4A, AAC, OGG, AIFF and more).
  2. Choose a report location. This is where the Excel file will be saved.
  3. Tick the options you want (see the next section). If your music has singing, tick My tracks have vocals.
  4. Press Analyze Music. A progress bar and a running log show what is happening. You can press Stop at any time and nothing is lost.
  5. Open the report, or press ⌘ F to open Search Library and start finding tracks.
Try “Preview only” first.It lists the files that would be analyzed without analyzing anything, so you can check you picked the right folders.

The Analyzer window

OptionWhat it does
Use Claude metadata enrichmentAdds the written description, mood words and keywords. See Claude and cost. Without it you still get a full report.
Listen to audio (AI)Runs the built-in listening model to find instruments, vocals, style and mood. Turn it off for a much faster, tag-only pass.
My tracks have vocalsTells the app to analyze the singing (male, female, choir, rap). Leave it off for instrumental libraries and every track is simply marked Instrumental.
Transcribe lyricsWrites the sung words into the report using a local speech model. Needs “My tracks have vocals”. See Vocals and lyrics.
Add to existing reportNew and changed tracks are added to the report you already have, instead of replacing it. Handy for adding a new album.
Re-use earlier resultsTracks you have already analyzed are not redone, which saves time and money. Turn it off to force a fresh analysis.
Save a CSV copyAlso writes a plain .csv next to the Excel file.
Preview onlyLists what would be analyzed. Nothing is analyzed or saved.
Open report when finishedOpens the finished report automatically.
Include subfoldersAlso looks inside folders within your chosen folders.
Audio sampleHow much of each track is listened to: 30 seconds, 60 seconds, 90 seconds or the whole track. Longer is a little more thorough and a little slower.
Album context (optional)A short note that helps the app, for example 1980s pop or Album Name=style; Another Album=style. You can also mention things you know, such as “female vocals” or “prominent piano”.

Most of these are also in the Options menu at the top of the screen.

Claude and cost

Claude is optional. Without it you still get genre, instruments, tempo, key, energy and basic moods. With it you also get a polished three-sentence description, richer mood words, search keywords and a short “Vibe Check” line.

Your API key

  1. Create a key at the Anthropic Console (Help ▸ Get an Anthropic API Key takes you there).
  2. Add a few dollars of credit (Help ▸ Add API Credits / Billing).
  3. Paste the key into the Anthropic API key box. It is stored in your Mac’s Keychain, never in a text file.

You pay Anthropic directly, and usage is typically a small fraction of a cent per track.

Choose a mode

ModeBest for
Smart – Haiku, Sonnet only for tricky tracksThe default. Fast and inexpensive. A stronger model is used only for tracks with no usable genre information.
Economy – Haiku 5.5The lowest cost for big libraries.
Best – Sonnet 5.5The most polished writing, at a higher price.

Vibe Check tone

The short, witty line in the Vibe Check column can be light wit with an occasional dark streak, dry and playful, or straight, with no jokes. Find it under Options ▸ Vibe Check tone.

Cost tracking.Every report row records which model was used and how many tokens it took, so you can see exactly what a run cost.

Vocals and lyrics

Vocal type

With My tracks have vocals on, each track gets one of: Male vocals, Female vocals, Choir / group vocals, Rap vocals, Vocals (synthetic-sounding) or simply Vocals when the voice type is unclear.

Know your singer? Tell the app.If the voice type comes out as just “Vocals”, add a note to Album context such as female vocals. The app will use it whenever the audio is a close call.

Lyrics

Turn on Transcribe lyrics to add the sung words to the Lyrics (auto) column. Choose how much of each song to read (About 2 minutes or Whole song) and which speech model to use:

  • Whisper medium: more accurate, larger one-time download (about 1.5 GB).
  • Whisper small: lighter and faster (about 500 MB), a bit less accurate.

Optionally, Analyze lyric themes with Claude adds a few theme words (love, loss, freedom…). Claude only sees a short excerpt, and never quotes it back.

Check lyrics before relying on them.Speech recognition is imperfect on music, so expect the occasional wrong word. Song lyrics may also be copyrighted, so treat the column as a search aid rather than a published transcript.

Your report

The Excel file has four sheets:

  • Music Library: one row per track.
  • About this report: what every column means and where it came from.
  • Summary: totals for the whole library.
  • Review Queue: tracks the app is least sure about, lowest confidence first, with the reasons.

The main columns

ColumnWhat it tells you
Genre, Style / Sub-genre, EraThe musical category, a more specific style, and the decade the sound evokes.
InstrumentsWhat the app heard, strongest first.
VocalsInstrumental, or the voice type.
MoodsSearchable feeling words, matched to the track’s energy.
Tempo (BPM), Tempo Feel, Rhythmic FeelMeasured speed, how fast it feels, and the groove (for example straight or swung).
Energy, KeyLow to very high, and the musical key.
DescriptionA short supervisor-style pitch for the track, ending with where it could be placed.
Keywords10 to 12 search terms.
Lyrics (auto), Lyric ThemesOnly when you turned lyrics on.
Analysis Confidence, Review FlagsA 0 to 100 “how much should I double-check this” score and the reasons. It is a guide, not a guarantee.
Classifier Detail (raw)The raw scores behind the answers, for the curious.
Your own edits are safe to make.The report is a normal spreadsheet. Fix anything you disagree with, and Search Library will use your corrections.

Search tips

Type thisTo find
sad pianoTracks matching both words anywhere in their details.
"slow build"The exact phrase.
-vocalsExclude a word. Great for instrumental-only searches.
mood:tenseSearch one field only.
inst:celloTracks with a cello.
bpm:90-110A tempo range.
era:1980sA decade.
rhythm:swungA groove.
energy:lowAn energy level.

Combine them freely: mood:hopeful inst:piano bpm:70-100 -vocals.

½× / 2× next to the BPM filter.Ticking it also matches half-time and double-time tempos, so a 70 BPM search also finds 140 BPM tracks that feel slow.

Press Esc to clear the search box. The Clear button resets the search and all filters.

Preview player and waveform

You can listen without leaving the app. The player sits across the bottom of the Search window and works on both the Results and Shortlist tabs.

  • Play a track: select it and press Play, press Space, or double-click the row.
  • Waveform: once a track loads you see its shape. The part already played is shaded and a red line marks where you are.
  • Jump anywhere: click the waveform. Click and drag to scrub back and forth.
  • Skip and volume: use the keyboard shortcuts below, or the volume slider.
First play needs a moment.A track is loaded fully before it plays, so a long track can take a few seconds. The very first time, the app also installs a small audio component. It tells you when it does.

If you select a different track while one is playing, the music keeps going. Press Play (or double-click) to switch to the one you selected.

Customizing the columns

  • Sort: click a heading. Click again to reverse.
  • Resize: drag the edge between two headings. If the columns are wider than the window, a scroll bar appears at the bottom of the table.
  • Reorder: drag a heading sideways. A blue bar shows where it will land.
  • Show or hide: click Columns ▾ (or right-click any heading) and tick the ones you want. Energy, Rhythm / Groove and Spreadsheet are hidden until you turn them on.
  • Start over: Reset column layout in the same menu, or View ▸ Reset Column Layout.

Your layout is saved and shared between Results and Shortlist, and it is still there next time you open the app.

Window size and position are remembered too, for both the Analyzer and Search windows, along with the divider between the results list and the track details.

The standard order is: Track, Artist, Genre, Style, BPM, Length, Key, Instruments, Tempo Feel, Moods, Era, Vocals.

Shortlist: your pitch list

Click + Shortlist on any track to collect it on the Shortlist tab. The list is saved between sessions.

  • Move up / Move down to set the running order.
  • Remove or Clear all to tidy up.
  • Export to Excel makes a clean pitch sheet with descriptions, keywords and file paths.
  • Copy as text list puts a numbered list on your clipboard, ready to paste into an email.
  • Copy audio files to a folder gathers the actual audio files, numbered in your order, ready to send or upload. Anything it could not find is listed afterwards.

Moved your music?

Reports remember where each file lived. If you move your music to a new drive or folder, you do not need to redo anything, and you do not need to fix tracks one by one. Reconnect the whole library at once:

  1. Press Moved your music? (or Track ▸ Moved Your Music?).
  2. Confirm the old folder. The app guesses it from your tracks, for example /Volumes/OldDrive/Music.
  3. Choose the folder where that music lives now.

Every track under the old folder, including subfolders, is now found under the new one, and the app tells you how many were found.

One thing to know.The folders inside must be arranged the same way as before. If some tracks are not found, they are either not in the new folder or sit in different subfolders. You can run it again with another old and new pair.

This only changes where the app looks. Your Excel reports are not rewritten.

Keyboard shortcuts

On a Mac, use ⌘ (Command). On Windows or Linux, use Ctrl.

Analyzer window

⌘ OChoose music folders
⌘ SChoose report location
⌘ ReturnAnalyze Music
⌘ .Stop
⌘ F or ⌘ 2Open Search Library

Search window

SpacePlay or pause the selected track
⌘ ← / ⌘ →Back or forward 10 seconds
⌘ ↑ / ⌘ ↓Volume up or down
⌘ .Stop and rewind
⌘ FJump to the search box
⌘ RReload reports
⌘ OChoose reports folder
⌘ DAdd to shortlist
⌘ LMore like this
⌘ ReturnOpen in default app
⌘ 1 / ⌘ 2Switch between the Analyzer and Search windows
⌘ WClose the window

Troubleshooting

The installer won’t open or stops with an error

  • Mac says it “can’t be opened” or is from an unidentified developer: right-click Install.command, choose Open, then Open again. Or go to System Settings ▸ Privacy & Security, scroll down, and click Open Anyway.
  • Mac says “permission denied”: unzipping can remove the permission to run the file. Use Terminal (see the backup plan) and type chmod +x Install.command, then ./Install.command.
  • Windows says “Windows protected your PC”: click More info, then Run anyway.
  • “No suitable Python found”: install Python 3.12 from python.org (see Installing). Newer versions such as 3.13 and 3.14 are not supported yet, and the Microsoft Store version of Python won’t work.
  • A download failed or it stops part-way: check your internet connection and that you have about 3 GB free, then simply run the installer again. It picks up where it left off.
  • The Windows window closes immediately: open the folder, type cmd in the address bar, press Enter, and run Install-Windows.bat from there so you can read the message.
  • Still stuck: follow the Terminal steps in the backup plan, which shows each step and any error message.

Command+Tab says “Python” instead of the app name (Mac)

Quit the app, run Install.command again, and open the new app from your Desktop. The installer builds the app as its own named program and checks that it works. If it didn’t apply, run the checker from the backup plan and look for the “app-name fix” line. Windows groups the window under the shortcut’s name, so this only affects Macs.

Buttons seem to ignore clicks (Mac)

This is a known problem with older versions of the window toolkit. Choose Help ▸ Button not responding? to check your version. If it is older than 8.6.13, install Python 3.12 from python.org and run Install.command again. Until then, the menu bar and the keyboard shortcuts always work.

The preview won’t play

  • If it says the file isn’t where the spreadsheet says, use Moved your music?.
  • The installer already adds audio playback. If the app says it can’t, run this in Terminal (Mac) ~/.music_analyzer/venv/bin/python -m pip install sounddevice or the black window (Windows) %USERPROFILE%\.music_analyzer\venv\Scripts\python -m pip install sounddevice, then try again.
  • Check your Mac’s output device and volume, and the app’s own volume slider.

An instrument looks wrong

The listening model sometimes mixes up similar sounds, especially in dense mixes. Three things help:

  • Add a hint to Album context, such as prominent piano or heavy synths.
  • Increase the Audio sample to 90 seconds or the whole track.
  • Check the Review Queue sheet for tracks flagged as uncertain, and fix those by hand in Excel.

The lyrics start with a stray line

Speech models sometimes “hear” a phrase over a quiet or instrumental intro. The app removes the common ones automatically. If a stray line gets through, just delete it in the spreadsheet.

Nothing was found when I searched

Check that the Reports folder points at the folder holding your .xlsx reports, tick Include subfolders if needed, and press Load / Refresh. Reports must have been made by Music Analyzer. Make sure a report isn’t open in Excel when you load it.

Where is the log?

Choose Tools ▸ Open Analysis Log. If something fails to start, details are in ~/Library/Logs/MusicAnalyzer.log (Mac). On Windows, run the app from the black window with %USERPROFILE%\.music_analyzer\venv\Scripts\python %USERPROFILE%\.music_analyzer\app\music_analyzer_app.py to see messages.

Questions people ask

Is my music uploaded anywhere?

No. The audio is analyzed on your computer. If you use Claude, only text facts about each track are sent, never the audio.

Do I have to use Claude?

No. Without it you still get a full report. Claude just writes nicer descriptions and keywords.

How long does it take?

It depends on your Mac and how many tracks you have. Re-running on tracks you have already analyzed is nearly instant because results are remembered. Turning on lyrics is the slowest option.

Can I add new music to an old report?

Yes. Keep Add to existing report ticked and point to the same report file. Only new or changed tracks are analyzed.

Can I change what the app says about a track?

Yes. Edit the spreadsheet. Search Library reads whatever is in it, so your corrections show up after you press Load / Refresh.

Does it work on Windows?

Yes. There is a Windows installer that adds a Desktop and Start menu shortcut. The Command+Tab name fix is Mac-only; Windows names the window after the shortcut.