How VinylCat finds a record

What it measures

Every frame is shrunk to a small greyscale thumbnail of the central region only, so hands at the edges do not count. Four numbers are computed per frame, each smoothed over the last five so a single flicker cannot flip the state.

The SHARP, STILL and RECORD bars in the app's Settings are these three thresholds, live, so you can see why a capture isn't firing.

Details that matter

• Hold credit, not a timer. Good frames add time to a one-second bucket; bad frames drain it at a third of the rate. Once a hold has started the thresholds relax, so the ring doesn't strobe.
• Drift check. A record sliding past looks "still" frame to frame, so the engine also compares against the frame the hold started from.
• Two modes. Identifying a new record waits for the record to be removed before re-arming. An extra shot of a matched record demands a burst of motion first, so a flip is required before the next capture.
• Hand-held iPhone. The motion and drift limits were raised so a Continuity-Camera iPhone in the hand can ever fill the ring.
• Manual mode. Switch CAPTURE off and only SPACE or "capture" takes a shot.

Three orientations, then a zoom pass

Labels are round and held at any angle, so the text pass runs three ways up. Then the smallest print is cropped, magnified two to four times, and read again. That zoom pass took "catalogue number somewhere in the candidates" from 84% to 91% of photos, at the cost of doubling the time.

The catalogue-number sieve

Every OCR line is upper-cased and run through one loose pattern: up to two short letter or digit groups, then a run of digits. That net catches "CHS TT 17", "2059 227" and "SRK 6095", but also years and speeds, so the filters do the real work:

• Drop bare four-digit numbers, "45" and "33". Years and RPM.
• Drop "A1", "B2" style side markers.
• De-duplicate ignoring spaces.
• Score by shape: letters first, then longer strings. Every rule in that scorer was earned by a photo the eval got wrong.

Details that matter

• OCR autocorrect is off. Apple's language correction would "fix" catalogue numbers into words. The raw glyphs are what's wanted.
• Comparison form. Whenever two catalogue numbers are compared, both are reduced to upper-case letters and digits, so "POSP-113", "POSP 113" and "posp113" all agree.
• Barcode shortcut. A barcode of eight digits or more skips the model entirely. A stray Code 39 fragment does not trigger it.
• No API key at all? The app still works, badly. It guesses "is this a label?" from words like RPM, SIDE A, MADE IN, picks the first long lines as label, title and artist, and lets the catalogue number carry the search. The HUD nudges you to add a key.
• The whole shortlist goes on to the Discogs layer, not just the winner. Labels print matrix and side suffixes too, and the first-ranked token is not always the one Discogs uses.

The answer shape

The model must return every one of these keys, null when unknown. Anything else is rejected before the app sees it.

Details that matter

• Image size. The still is downscaled to 1024 px on the long side and JPEG-compressed before upload, plus the zoomed close-ups from the local pass. That caps the per-image token cost.
• Strict output. OpenAI gets a JSON schema in strict mode; Google gets a response schema at low temperature. The reply cap is 2,500 tokens, because reasoning tokens count against it and a smaller cap cut the JSON off mid-field.
• Cost meter. Every reply's token counts are priced and added to the session total in the HUD's LLM COST cell.
• A model failure never aborts a scan. Timeout, bad key, malformed reply: the app carries on OCR-only and records the error against the scan.
• When OCR and the model disagree, the model wins. In the eval it gets the catalogue number right first time on 88% of photos against OCR's 49%.

The ladder

Every OCR candidate gets its own rung-3 attempt, so a mis-ranked token still gets searched.

A worked example

The model reads a Polydor 7" label as New Order, Blue Monday, Polydor, POSP 113. OCR also produced POSP 113. No barcode. Session format is 7". The first call that returns hits ends the run:

/database/search?type=release&per_page=15
  &label=Polydor&catno=POSP%20113&format=7%22

/database/search?type=release&per_page=15&catno=POSP%20113

• Rate limit is read from Discogs' own headers and kept at 60 a minute with headroom. Valuation after a Collection pull runs one call every 2.2 s so scanning keeps most of the budget.
• No token means the public limit of 25 a minute and no writes to your Collection.

Scoring weights

Points are added per hit and clamped to 0 to 1. The reasons are kept and shown in the HUD's meta line, for example 0.94 · r2413807 · catno title format.

An exact catalogue number plus a good title plus the right format lands around 0.85 on its own. A barcode plus title does the same. Artist and title alone can never pass 0.85, which is the point: names alone cannot tell pressings apart.

Details that matter

• Text similarity is Jaro–Winkler on lower-cased, punctuation-stripped strings with a leading "The" removed. It rewards shared prefixes, which suits titles.
• Swapped artist and title are tolerated: the ranker tries the whole "Artist – Title" string and each part against each part, and takes the best.
• "Strong" means an exact catalogue number or barcode and a title match. A strong hit is accepted even below 0.85. This is the safety net for scores dented by a wrong format guess.
• Look-alikes. Two Discogs entries with the same label, catalogue number, country and year cannot be told apart from a photo, so they are folded into one before deciding. Without this, every reissue would trigger a "which one?" question.
• Ambiguous lists every distinct pressing within 0.25 of the top score, three to nine of them, each as headline plus label, catno, country, year and format. Keys 1 to 9 or the spoken number pick one.

Match lane

• Duplicate check is by Discogs release id. A second copy is allowed, but only if you say "add anyway".
• What gets saved comes from the full Discogs release, not the search hit: artist line, title, label, catalogue number, format, year, country, genres, styles, tracklist, cover image. Alongside it, the photo, the OCR lines, the model's reading, every ranked candidate and the score. That is the evidence Review and the thumbs-down verdict work from.
• One photo per record, the identifying one. Extra shots are only ever asked for by hand: "flip", "back cover", "gatefold", "disc two", and the record closes again after each one.
• Spoken confirmation: "The Jam, Going Underground, 1980, seven inch." Then the next record.
• Discogs sync, if you switched it on, adds the release to your Collection in the background and fetches a value in your currency.

Ambiguous and none lanes

• The camera is frozen while a question is on screen, so the next steady frame cannot wipe the list. SPACE and "capture" still work.
• Second look. Flip the record while the list is up and the new read runs the whole pipeline again; if exactly one candidate survives both reads, it is accepted and both photos are kept.
• Label first. When a cover shot fails to match, the app assumes the label will do better, switches the camera to shot mode and tells the model to expect a label. Only if that also fails does it offer one retry, then park the record.
• Parked means the Review tab, with everything read so far. Type a few extra words: a catalogue number in them is pulled out and searched exactly, the rest goes in as free text, and the same ranker orders the results.
• Errors park too. Discogs down, network gone: the photo goes to Review with a plain-words note, and nothing is lost.