Finishing Kord: True Streaming for Google Drive FLAC Playback

This is a submission for the GitHub Finish-Up-A-Thon Challenge

What I Built

Kord is my iOS-first, multiplatform SwiftUI music player for people who care about their own music library.

The first version started from a very personal itch: I wanted a native app for my FLAC collection that built through Qobuz and bandcamp that felt closer to how I actually listen. Albums first. Artwork up front. A real queue. Metadata that matters. Lossless playback details visible enough to trust, but not so loud that the app turns into a lab instrument.

I care about that world because I live in it a little. I listen on HD600s through a desktop chain, I use parametric EQ, and I notice when a music app treats local files like an afterthought. Kord was my attempt to build the opposite: a player that makes a personal library feel alive again.

By the time I came back to the project for this challenge, Kord already had a lot of the shape I wanted: a SwiftUI library, album views, artist pages, playlists, Last.fm work, artwork enrichment, Google Drive import, and a native audio path. But one part was still clearly unfinished.

Google Drive playback worked, but it was not really streaming.

Before this finish-up push, the reliable path was cache-backed: import a Drive track, download the whole FLAC, then play it like a local file. That was stable, but it made large albums feel heavy. A cloud library should not make the listener wait for the app to secretly become a file downloader.

The comeback goal was to cross that line: make an uncached Google Drive FLAC start through true byte-range streaming, while keeping the stable local cache path as a fallback.

Demo

The short demo shows the public-facing side of Kord: opening the library, jumping into an album, starting a track, and expanding Now Playing with sample rate, channel count, bit depth, and signal-path information.

For the Google Drive side, this is the important settings screen:

Kord connects to Google Drive with read-only access, lists FLAC files from the selected music folder, and streams their bytes for playback. The Drive settings screen also shows the cache behavior, because caching is still part of the design: streaming should make the first listen fast, then cache should make the second listen instant.

Before / After

Before:

• Google Drive playback depended on full-file cache-backed playback.
• The app could feel like it was importing remote music more than playing it.
• Partial data was dangerous because a partial FLAC should never pretend to be a complete cached file.
• Seeking and decoder reads needed a more careful boundary than "just download some bytes."

After:

• Uncached Drive tracks with a known remote byte size can open a Range-backed decoder source.
• The streaming path uses HTTP Range requests instead of requiring a full-file download up front.
• The Range reader reuses fetched chunks and coalesces in-flight requests.
• Short responses are validated instead of silently passed to the decoder.
• Streamed chunks write through to a hidden partial cache file.
• The partial cache promotes to the normal cache only after every byte range is covered.
• The older cache-backed path still exists as the fallback, so this was an architectural upgrade, not a reckless replacement.

The Comeback Story

The part that made this project interesting was that "stream a FLAC from Google Drive" sounds much simpler than it is.

If this were a normal file download, the problem would be boring: request the file, save the file, play the file. But Kord is a music player, and music playback has different rules. The decoder may ask for bytes from the middle of the file. The audio engine needs steady buffers. The user might seek. The network might return a short response. OAuth might expire. And if the app writes a half-fetched FLAC into the normal cache, the next playback attempt can fail in confusing ways.

So I treated the finish-up as a real playback architecture problem.

The first step was separating responsibilities. DriveTrackLoader became the place where Drive-specific playback setup lives. Full downloads and Range requests now share media request construction through the Google Drive client, instead of having two almost-identical paths drifting apart.

Then came the streaming reader. DriveStreamingRangeReader is an actor that serves arbitrary byte windows from Google Drive. It caches chunks, reuses in-flight fetches, validates exact byte counts, and primes read-ahead for sequential decoder reads.

That actor choice mattered. Swift actors serialize access to their mutable state, which is useful here because streaming state is shared across reads, cache writes, and seek behavior. I did not want a pile of locks around chunk dictionaries and in-flight network tasks.

The next piece was bridging that async Drive reader into the decoder world. Kord uses SFBAudioEngine for the streaming path, with a custom input source that can answer synchronous decoder reads by pulling from the Range-backed reader. Normal playback scheduling then feeds bounded decoded PCM buffers into AVAudioPlayerNode.

That sounds abstract, but the user-facing result is simple:

Tap a Drive-backed FLAC. If Kord knows the remote byte size and the track is not already cached, it can choose the streaming backend. If anything about that path is not safe, it falls back to the older cache-backed path.

That fallback is important. I did not want to "finish" the app by making it more fragile.

The most satisfying part was the cache policy. During streaming, Kord writes fetched chunks into a hidden partial file. Only when every byte range is covered does that file promote into the normal Drive cache. That means the first listen can be streamed, but the second listen can behave like local playback. It also means a half-streamed file never masquerades as a valid FLAC.

This was the moment the project started to feel finished in the way the challenge asks for. Not perfect. Not done forever. But meaningfully revived.

Kord moved from "I can technically play music from Drive after enough downloading" to "I have the core of a real remote-library playback engine."

My Experience with GitHub Copilot

GitHub Copilot was most useful as a pair programmer for the parts of the project where the hard work was not typing code, but keeping the architecture straight.

The true-streaming change touched Swift concurrency, SwiftData metadata, Google Drive API requests, SFBAudioEngine decoding, AVFoundation scheduling, cache semantics, and tests. It would have been easy to make a change that compiled but quietly broke the playback model.

The workflow that helped was small and iterative:

1. Describe the real end state in plain English.
2. Ask Copilot to help split it into milestones.
3. Implement one narrow part.
4. Use tests and simulator evidence to challenge whether that part actually proved anything.
5. Update the TODO so the project history stayed honest.

Copilot helped me reason through edge cases that are easy to underestimate:

• What happens when Google Drive returns fewer bytes than requested?
• How do we keep partial cache files from looking complete?
• Where should the fallback boundary live?
• Which state belongs in an actor?
• How does seek behavior affect read-ahead?
• Which tests prove byte-range correctness without needing a real network call?

The biggest lesson was that AI help is most valuable when I keep it constrained. I did not ask for a giant rewrite. I used it to keep pressure on one slice at a time: Range reader, decoder bridge, cache write-through, diagnostics, tests, and then simulator proof.

It also helped me be more honest about the word "done." A green build is not enough for an audio app. Passing tests is not enough either. Kord now has focused tests, full test-suite coverage for the streaming pieces, simulator launch proof, and logged simulator evidence of the true-streaming path selecting HTTP Range playback. But I still think the final release gate is real-device listening under worse network conditions: seek, pause, next, mixed sample rates, lock-screen controls, and gapless transitions.

That is the kind of boundary I want in a serious music app. The finish-up work brought Kord across the architectural line. The remaining work is hardening, not discovering whether the idea is possible.

What Changed Under The Hood

The most important pieces of the comeback were:

• DriveTrackLoader: Drive-specific playback setup and fallback selection.
• DriveStreamingRangeReader: actor-backed HTTP Range reading with chunk reuse, in-flight request coalescing, read-ahead, seek priming, and short-response validation.
• ASJBlockInputSource: the bridge between SFBAudioEngine's decoder reads and Kord's Range-backed source.
• DriveCache: hidden partial write-through files that promote only after complete coverage.
• StreamingDiagnostics: logs for backend selection, Range requests, fallback reasons, playback start, and cache promotion.

This is the part I am proudest of: the project did not just get a prettier screen. It got a more honest playback model.

What Is Next

The next work is stress testing the true-streaming path on a real iPhone:

• Play uncached Drive FLACs on slower networks.
• Seek into regions that have not been fetched yet.
• Test pause/resume and lock-screen controls.
• Test next/previous with mixed sample-rate albums.
• Harden gapless transitions with streaming sources.

But the comeback is real. Kord is no longer just a local FLAC player with Drive import attached. It is becoming the cloud-aware, lossless-focused player I wanted when I started.

And that is exactly why this project was worth finishing.