Vinyl Scrobbler

Install the working app

Test Vinyl Scrobbler through the public TestFlight link. Install the iOS version on an iPhone and the native macOS version on a Mac for the intended experience.

Vinyl Scrobbler is a native SwiftUI application for iPhone and Mac. It recognizes music playing through a nearby speaker with Apple ShazamKit, confirms repeated detections, and sends confirmed plays to the listener's authorized Last.fm account.

This repository contains the source corresponding to version 1.0 (build 6). It intentionally contains no production API credentials, signing identities, reviewer passwords, or build artifacts.

Why I built it

I love listening to vinyl records, and I am a little obsessed with music statistics. I keep my listening history on Last.fm, but music played from a record, a speaker, or at a concert does not naturally become part of that online history. I wanted a simple way to connect those offline listening moments to my Last.fm account.

I am not a software developer, which is exactly what made this project exciting to me: I wanted to find out whether I could turn my own idea into a real native application by working closely with AI.

Building it with Codex and GPT-5.6

I began with a plain-language prompt describing the problem and the first version I wanted to test. Codex and I then worked iteratively: research showed that Apple's ShazamKit could provide reliable music recognition, which gave the project a strong technical foundation and accelerated the first working prototype.

The idea, product direction, and final decisions were mine. I wanted the application to feel immediate, friendly, and at home in the Apple ecosystem: no traditional onboarding, one central listening control, minimal status text, native navigation, and optional color themes. I repeatedly tested the iPhone and Mac versions, corrected behavior and layout, rejected visual ideas that felt too heavy, and refined the animations until the experience felt simple rather than technical.

Codex with GPT-5.6 Sol performed most of the implementation under my direction. It helped design the shared SwiftUI architecture, connect ShazamKit, implement repeated-match confirmation, sign Last.fm API requests, store authorization in Keychain, preserve local history, retry offline scrobbles, build the iPhone Live Activity, prevent sleep during Mac sessions, create the animated visual system, diagnose platform-specific bugs, and prepare tested release builds. It also helped keep the code organized and the application lightweight.

I reviewed the results continuously and tested the complete flow with real music and my own Last.fm account. This was a genuine collaboration: I supplied the idea, taste, priorities, testing, and product decisions, while Codex translated that direction into most of the working code at a speed and level of consistency I could not have achieved alone.

GPT-5.6 is not called by the finished application at runtime. It was the development intelligence used through Codex to research, design, implement, debug, and refine the product.

How it works

The experience is deliberately small:

1. Allow microphone access.
2. Connect a Last.fm account.
3. Tap the listening button.

The listener can leave an iPhone or Mac near a turntable, a speaker, or another music player. Vinyl Scrobbler checks the surrounding audio with ShazamKit and requires repeated matching detections before sending a scrobble, reducing accidental matches. The same idea can even be used at a live concert, making a personal listening history more complete than streaming history alone.

It is a niche application, but it solves a real problem for people who care about both physical music and detailed listening statistics: it brings vinyl, concerts, and other offline listening back into an online music history.

Technical overview

• One Swift codebase with native iPhone and macOS targets.
• Explicit user-controlled microphone sessions using SHManagedSession.
• A candidate/confirmation engine that prevents a single uncertain match from being scrobbled.
• Configurable recognition intervals: 45 seconds requires three matching checks; 60 or 90 seconds requires two.
• Browser-based Last.fm authorization; the resulting username and session key are stored in Keychain.
• SwiftData session history and a deduplicated offline queue with capped exponential retry.
• A Live Activity on supported iPhones and sleep prevention during active Mac sessions.
• No developer-operated backend, advertising SDK, analytics SDK, or audio recording.

Repository map

• Sources/ — shared application, UI, models, recognition, Last.fm, persistence, and Keychain code.
• LiveActivity/ and Shared/ — iPhone Live Activity extension and shared activity attributes.
• Tests/ — decision-engine tests.
• Configuration/ — non-secret build configuration and a credentials example file.
• Docs/ — ShazamKit, Last.fm, signing, and troubleshooting notes.
• JUDGES.md — the shortest path for evaluating the working build.
• CODEX_AND_GPT56.md — technical evidence and author-completed development narrative.

Requirements

• Xcode 26.2 or compatible.
• XcodeGen: brew install xcodegen.
• Deployment targets: iOS 17.0 and macOS 14.0.
• A physical Apple device and an Apple Developer team with ShazamKit enabled for real catalog recognition.
• A separate Last.fm API application for local end-to-end scrobbling.

Compile and run tests without credentials

The project compiles without production credentials. Create a local placeholder file, generate the project, and run CI:

cp Configuration/Secrets.xcconfig.example Configuration/Secrets.xcconfig
./Scripts/generate_project.sh
./Scripts/ci.sh

Placeholder credentials keep Last.fm connection disabled but do not affect compilation or decision-engine tests.

Local end-to-end setup

1. Register your own Last.fm API application.
2. Replace the placeholders only in the ignored Configuration/Secrets.xcconfig file.
3. Set your own Apple DEVELOPMENT_TEAM in Configuration/Base.xcconfig or Xcode.
4. Enable ShazamKit for your explicit App IDs.
5. Regenerate the Xcode project and run on a physical iPhone or Mac.

Detailed instructions are in Docs/BUILD_AND_SIGNING.md, Docs/SHAZAMKIT_SETUP.md, and Docs/LASTFM_SETUP.md.

Judge testing

To test the fully configured application with real music recognition and scrobbling, install it through the public TestFlight link. For the best experience, install the iOS version on an iPhone and the native macOS version on a Mac. Judges are not expected to rebuild the service-integrated application from source. Expected timing and the complete test procedure are documented in JUDGES.md.

Reviewer credentials must never be committed to this repository. They will be supplied only through the private Devpost testing instructions.

Privacy and security

Audio is processed transiently by ShazamKit and is never written to disk or sent to a developer-operated server. Local history remains on device. Only confirmed track metadata and timestamps are sent to the connected Last.fm account.

See PRIVACY.md, SECURITY.md, and THIRD_PARTY_SERVICES.md.

Codex and GPT-5.6

Additional file-level evidence of how Codex and GPT-5.6 contributed to architecture, implementation, testing, and release work is documented in CODEX_AND_GPT56.md.

License

MIT. See LICENSE.