People who still buy music mostly get it as a ZIP. Bandcamp, Qobuz and most download shops hand you one archive per album. My offline music player, Clickwheel, could only import loose audio files, so the first thing a new user had to do was find an unzip tool on their phone. That is a bad first minute.
So I added ZIP import. The diff was 469 lines across 13 files, and almost none of it was "call the unzip function". Here is what the rest was.
1. Stream from disk, off the UI thread
A FLAC album is easily several hundred megabytes. Reading it into a Uint8List on a phone is asking for an out-of-memory kill. The archive package (4.x) can decode from a file stream and write each entry straight to disk:
static List<String> unpackZip(String zipPath, String destPath) { final input = InputFileStream(zipPath); final written = <String>[]; try { final archive = ZipDecoder().decodeStream(input); for (final entry in archive) { if (!entry.isFile) continue; final relative = safeZipEntry(entry.name); if (relative == null || !kAudioExtensions.contains(_extension(relative))) { continue; } final file = File('$destPath/$relative'); file.parent.createSync(recursive: true); final output = OutputFileStream(file.path); try { entry.writeContent(output); } finally { output.closeSync(); } written.add(file.path); } } finally { input.closeSync(); } return written; } The function is synchronous on purpose. It is a static method that only takes two strings, so it can run in a background isolate with one line:
final unpacked = await Isolate.run(() => unpackZip(zip, dest)); The click wheel keeps animating while the album unpacks, and the progress label ("Unpacking Some Artist - Some Album.zip") is set from the main isolate between archives.
2. Never trust an entry name
A ZIP entry name is just a string chosen by whoever made the archive. ../../something is a valid name, and writing it blindly puts a file outside your target folder. This is the classic "zip slip" bug. My guard is small and boring:
static String? safeZipEntry(String name) { final parts = name .replaceAll(r'\', '/') .split('/') .where((p) => p.isNotEmpty && p != '.') .toList(); if (parts.isEmpty) return null; if (parts.contains('..')) return null; if (parts.first == '__MACOSX') return null; if (parts.last.startsWith('._')) return null; return parts.join('/'); } Four things happen here:
- Backslashes become slashes, because archives made on Windows sometimes use them.
- Empty segments are dropped, so an absolute path like
/abs/song.mp3becomes the relativeabs/song.mp3. - Any entry containing
..is rejected outright. I don't try to normalise it. An album has no reason to contain one. - The macOS Finder junk is skipped: the
__MACOSXfolder and the._song.mp3resource forks. Those end in.mp3, so without this line every album zipped on a Mac would show up with twice as many tracks, half of them unplayable.
On top of that, only files with a known audio extension are written at all. Cover scans, PDFs and .url files stay in the archive.
3. Test with archives you build in the test
I work as a QA engineer, so this is the part I care about most. The archive package can also create ZIPs, which means the test builds its own hostile album in memory:
final archive = Archive() ..addFile(ArchiveFile.bytes('Artist - Album - 01 One.mp3', [1, 2, 3])) ..addFile(ArchiveFile.bytes('cd2/02 Two.flac', [4, 5])) ..addFile(ArchiveFile.bytes('cover.jpg', [9])) ..addFile(ArchiveFile.bytes('__MACOSX/._x.mp3', [0])) ..addFile(ArchiveFile.bytes('../evil.mp3', [0])); final zip = File('${dir.path}/album.zip') ..writeAsBytesSync(ZipEncoder().encode(archive)); final out = LibraryService.unpackZip(zip.path, '${dir.path}/out')..sort(); expect(out, [ '${dir.path}/out/Artist - Album - 01 One.mp3', '${dir.path}/out/cd2/02 Two.flac', ]); expect(File('${dir.path}/evil.mp3').existsSync(), isFalse); Five entries go in, two come out, and the last line checks that nothing landed one folder up. No fixture files in the repo, no binary blobs in code review.
4. Decide where the album goes
Small decisions that took longer than the code:
- Folder name = archive name without
.zip. Bandcamp already names its downloads "Artist - Album", so the folder view looks right for free. An archive literally called.zipfalls back to a default name instead of creating a folder with an empty name. - Subfolders survive.
cd1/andcd2/stay as they are. - The scratch folder is deleted in a
finallyblock, whether the import worked or not. Otherwise a failed import of a 600 MB album silently eats 600 MB. - A ZIP dropped into the media folder is deleted after a successful unpack, because otherwise every album is on the device twice. A broken archive stays where it is, so the user can see it.
- Name clashes never overwrite. A second "Some Album" becomes "Some Album (2)".
5. iOS: show up in the share sheet
On iOS most people download the ZIP in Safari and then tap Share. To appear there, the app declares the document types in Info.plist:
<dict> <key>CFBundleTypeName</key> <string>ZIP</string> <key>CFBundleTypeRole</key> <string>Viewer</string> <key>LSHandlerRank</key> <string>Alternate</string> <key>LSItemContentTypes</key> <array> <string>public.zip-archive</string> </array> </dict> LSHandlerRank is Alternate on purpose. A music player should be offered for ZIP files, not become the default app for them.
The native side is a small Swift class that receives the URL, wraps the copy in startAccessingSecurityScopedResource() and moves the file into the media folder. The detail that bit me: on a cold start the file arrives before the Dart side is listening on the method channel. So the Swift side counts what came in, and Dart asks once at startup:
_channel.setMethodCallHandler((call) async { if (call.method == 'filesArrived') await _absorb(ipod); }); // Whatever arrived on cold start, before Dart could listen. _absorb(ipod, onlyIfPending: true); What I'd tell my past self
The unzip call is ten lines. The feature is everything around it: memory, the UI thread, hostile paths, Finder junk, cleanup, duplicates and cold starts. Writing the test list first would have given me the design for free.
Honest status: this is merged on the main branch and ships with the next store update. If you install the app today, ZIP import may not be in your build yet.
Clickwheel is an offline music player with a click wheel for your own MP3 and FLAC files, on iPhone and Android. You can turn the wheel in your browser: https://clickwheel-app.pages.dev/?ref=devto#rad
Clickwheel by Felix Helleckes. More of my apps: https://felix-helleckes.github.io/apps/?ref=devto
Disclosure: this article was written by an AI assistant from the real code and commit history of the project, and is labelled as AI generated.
![Physical AI Engineering — Ch.04: Localization Mapping and World Understanding [EN]](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fuscy0mautxl2mb4834vd.png)

