Troubleshooting

Shazam returns the "wrong" track — that's serendipity

Sometimes you Shazam a track at a club and the result is clearly not what was playing. The Shazam algorithm's recognition isn't perfect; it can match on a similar bassline, a sampled vocal, a near-cousin remix.

Don't treat this as broken. Treat it as a discovery candidate. The "wrong" track can still be worth a listen. Listen to it. If you'd play it in a set, green. If not, red. Either way, you got a tip you wouldn't have otherwise.

Recordings throw up false positives — and why you should welcome them

Batch-Shazamming a long recording — a 2-hour DJ set, a club night, a stream — will sometimes return matches that weren't actually in the source. Three things drive this:

1. The Shazam algorithm's recognition isn't perfect. It misses, mis-identifies, and pulls in near-cousin tracks when it can't quite lock onto the real one.
2. Recording quality affects hit rate. A phone in your pocket at a venue captures less cleanly than a direct mixdown. Recognition suffers.
3. Many DJ tracks are unreleased. White labels, dubplates, ID-only edits — they're not in Shazam's catalog at all and never resolve.

Recognition keeps improving and we want it to. But the upside of the current state is real: because classification is so fast in CatchIt!, "wrong" matches aren't really wrong — they're tracks worth a quick listen. The cost of dismissing one is a single tap.

If the noise is overwhelming, increase Minimum Matches in Settings → Tracks Recognition (Shazam) — that trades discovery for cleanliness. See Importing tracklists & playlists.

Voice-recording quality depends on environment

CatchIt! works with whatever audio file you give it. The quality of the recognition depends on how loud the music is relative to ambient sound, how close your recorder was to the source, and whether your phone was in a pocket vs on a table. A recording of a club set with the phone in your pocket gets you a respectable hit rate. A recording of the dinner conversation next to the speakers gets you very little. There's no setting that fixes physics.

Streaming-library availability gaps

A track that's on Apple Music might not be on Spotify, and vice versa. Some are vinyl-only. Some are regional. Some are temporarily unavailable. There's nothing CatchIt! can do about this — we work with whatever the streaming services have.

If you have both Apple Music and Spotify subscriptions, you maximize coverage by switching the active service when a track isn't on your default.

Spotify gives you the wrong version

Spotify search isn't deterministic. CatchIt! runs a cascade of search strategies to find the right version, and most of the time it lands. But for tracks with many remixes, extended cuts, or generic names, it sometimes returns a different version than what was Shazammed.

The Apple Music side is deterministic via Shazam's Apple Music ID, so it doesn't have this problem. If you find a Spotify mismatch: run Re-search all on the scope to try again, or switch to Apple Music for that track if you're subscribed to both. See Playback & streaming services.

Tracklist import — garbage in, garbage out

CatchIt! reads title and artist from whatever you import. If a 1001tracklists entry has the wrong artist, we'll search for the wrong artist. If a CSV has typos, we'll search for typos. We don't second-guess the input. If the source data is clean, the cascade does its best.

A track won't play — researched or not?

Two different states look similar but mean different things:

• Not yet researched. The play button is disabled and the row shows no per-platform pills — that absence is the signal. This is the most common reason a track looks "not playable": you haven't run Research on the scope yet. Not a problem, a step.
• Researched, not found. The play button stays disabled, but the pills now show a "not found" outcome per platform, and the search summary counts it. The track genuinely isn't on either service — vinyl-only, obscure, regional, or temporarily pulled. You can still classify it from memory; you can't preview it.

Apple Music doesn't start playing

When an Apple Music track won't start, the player header shows a red error: "Apple Music didn't start playing. Try again, or use Reconnect in Settings › Apple Music." Hover it for the full text; the ✕ dismisses it.

1. Try again. Hit play on the track once more.
2. Reconnect. Open Settings → Player Settings → Apple Music and click Reconnect. It clears the app's cached Apple Music state and checks your access and subscription again.
3. Check access. If the status reads Denied, turn Apple Music access back on in System Settings → Privacy & Security → Media & Apple Music.

Tracklists on iPhone — a tracklist is missing or a track won't play

The iOS Tracklists tab plays through Apple Music only (see Tracklists on iPhone).

• A tracklist isn't there. Tracklists come from your Mac: import it there and let the Mac sync, then pull down on the iPhone's Tracklists list to refresh. Tracklists marked completed on the Mac are hidden on the phone — Mark Incomplete on the Mac brings one back.
• "Apple Music access is off". Tap Open Settings and enable Media & Apple Music for CatchIt!.
• Rows tagged "Not on Apple Music". The phone only plays tracks your Mac has matched on Apple Music. If the tracklist hasn't been researched on Apple Music yet, run Research on it on your Mac with Apple Music, let it sync, and pull down on the phone. Some tracks simply aren't on Apple Music.
• A "Playback" alert. "An Apple Music subscription is required for playback" — playing on the iPhone needs an active Apple Music subscription (you can still browse). "This track is not available on Apple Music" or "Track not found in the Apple Music catalog" — that track can't play; move on to the next one. A track whose Apple Music lookup fails stays unplayable until you relaunch the app, so relaunch to give it another try.
• "Tracklists need a connection". The tab doesn't work offline. Reconnect — anything you already marked is saved and will sync.

"Update required" prompts

Sometimes when you launch CatchIt! macOS we'll prompt you to update before continuing. It's how we keep your local data safe when we ship behind-the-scenes upgrades to the schema or sync engine. The update takes a minute, and you can't dismiss the prompt. If you can't update right now (you're in the middle of a session), quit the app and come back when you can.

After an update, the inbox looks empty

Don't panic. After certain updates CatchIt! rebuilds your local library from the cloud — this is intentional. Your data is safe in the cloud; the local Mac copy is re-syncing. Wait a minute or two with your Mac online and everything repopulates.

A capture isn't showing up on the Mac

Sync is real-time when both devices are online. If a capture is stuck:

1. Check both devices are online. Cellular or WiFi.
2. Pull-to-refresh on iOS — open the Shazams tab and pull down.
3. Bring the macOS app to the foreground — it pulls fresh on focus.
4. Background the iPhone app and reopen it — that triggers a sync flush.
5. Check Settings → Sync on the Mac. If the Status reads "N changes not uploaded", click Retry Failed. Your work is saved on the Mac in the meantime — a failed upload never throws it away.
6. Sign out and back in on whichever device is stuck. Your data lives in the cloud — nothing is lost.

If captures still aren't syncing, email support@catchit.io with: which device is stuck, when you noticed, and the track you tried to capture.

Duplicates — how dedupe really works

Two captures count as the same track only if they share an Apple Music ID or a Spotify ID. So:

• Same track captured from two sources (Shazam + tracklist + voice rec) → unified into one row, with the source history visible
• Original mix vs Extended Mix vs Remix → different platform IDs, so CatchIt! treats them as different tracks. (You may classify the original green and the remix red, or vice versa.)
• Same audio mastered for different regions → different IDs, different rows. Rare, but it happens.

The Wishlist shows the dedupe history as a chip on each row — you always see your own prior verdicts before you classify again. The Inbox's Previous filter uses the same signal.

Maintenance & support tools

A few controls in Settings exist for exactly the moments this chapter covers (full tour in Settings):

• Retry Failed (Settings → Sync) — re-sends changes that couldn't be uploaded.
• Share error logs with developer (Settings → Advanced) — sends diagnostic logs to help fix a problem.
• Show in Finder (Settings → Data Storage) — opens the folder where CatchIt!'s local data lives, e.g. to back it up.
• Reset All Settings (Settings → Advanced) — clears your in-app preferences (thresholds, toggles) but does not touch your library or classifications. A factory reset for preferences only.
• Check for Updates… (Settings → Updates, or the app menu) — manual update check; two toggles control automatic checking and automatic download.

Still stuck? support@catchit.io — include what you did, what you expected, and what happened instead.