Audio metadata I/O library wrapping TagLib via spfk-taglib and Core Audio to provide unified tag reading/writing, marker parsing, embedded artwork, and broadcast wave (BEXT) support across common audio formats. AVFoundation alone lacks write support and misses RIFF markers, BEXT chunks, iXML, and chapter frames — SPFKMetadata fills those gaps with an ObjC++/C bridge.

Note: Pure data types (TagKey, TagProperties, MetaAudioFileDescription, AudioMarkerDescription, BEXTDescription, etc.) have been extracted to spfk-metadata-base. That package has no C++/TagLib dependency and can be used standalone. SPFKMetadata re-exports these types and adds file I/O on top.

SPFKMetadata serves ShadowTag's specific metadata workflows first. It's published as a reusable package because the C++/TagLib bridge is genuinely useful in isolation, but new features are vetted against whether they fit ShadowTag's use cases.

• Platforms: macOS 13+, iOS 16+
• Swift: 6.2+
• C++20

import SPFKMetadata

// Parse all metadata from an audio file
var description = try await MetaAudioFileDescription(parsing: url)

// Read tags
let title = description.tag(for: .title)
let artist = description.tag(for: .artist)
let bpm = description.tempo

// Write tags
description.set(tag: .title, value: "New Title")
description.set(tag: .genre, value: "Electronic")
description.set(customTag: "MY_CUSTOM_TAG", value: "custom value")
try description.save()

// Read BEXT chunk (WAV only)
if let bext = description.bextDescription {
    print(bext[.originator])
    print(bext.timeReferenceString)
    print(bext.loudnessDescription)
}

// Read iXML metadata (WAV/FLAC)
if let ixml = description.ixmlMetadata {
    print(ixml.scene ?? "")
    print(ixml.take ?? "")
    // Descriptor-based access
    let descriptor = IXMLTagDescriptor.descriptor(forIdentifier: "scene")
    print(ixml.value(for: descriptor) ?? "")
}

// Read markers
for marker in description.markerCollection.markerDescriptions {
    print("\(marker.name ?? "Untitled") @ \(marker.startTime)s")
}

// Read embedded artwork
if let image = description.imageDescription {
    let cgImage = image.cgImage
    print("\(cgImage.width)×\(cgImage.height)")
}

// Write embedded artwork
if let pictureRef = TagPictureRef(
    url: artworkURL,
    pictureDescription: "Front Cover",
    pictureType: "Front Cover"
) {
    description.imageDescription = ImageDescription(pictureRef: pictureRef)
    try description.save()
}

// Remove embedded artwork
description.imageDescription = nil
try description.save()

// Read/write star rating (0 = unrated, 1–5 stars) — preferred path
let rating = description.tag(for: .rating)    // "0"–"5" string, or nil
description.set(tag: .rating, value: "4")
try description.save()

// Standalone path-based access (opens its own FileRef — use for isolated rating I/O)
let stars = TagRating.read(url.path)          // -1 on error, 0 if unrated
TagRating.write(4, toPath: url.path)          // write 4 stars
TagRating.write(0, toPath: url.path)          // clear rating

// Copy tags between files
try TagProperties.copyTags(from: sourceURL, to: destinationURL)

Types marked with (base) are defined in SPFKMetadataBase and available without TagLib. Types marked with (I/O) are defined in this package and require the C++/ObjC bridge.

• MetaAudioFileDescription (base) — Top-level Codable struct aggregating tag properties, audio format info, BEXT data, iXML, markers, and embedded artwork.
• MetaAudioFileDescription+IO (I/O) — Parsing initializer and save() method with format-specific dispatch (WAV via WaveFileC, FLAC via FlacFileC, other formats via TagLib/AVFoundation).

• TagKey (base) — 100+ case enum serving as the canonical key type, mapping to both ID3 frames and RIFF INFO tags.
• TagProperties (base) — Struct wrapping TagData with tagLibPropertyMap for bridge interop.
• TagProperties+IO (I/O) — Load/save via TagLib across MP3, WAV, AIFF, FLAC, OGG, M4A, and other formats.
• TagPropertiesAV (base) — AVFoundation-based tag reader (read-only) for formats where TagLib support is limited.
• TagData (base) — Container wrapping a TagKeyDictionary and custom tags dictionary, with merge support via DictionaryMergeScheme (.preserve, .replace, .combine).
• TagGroup (base) — Enum grouping TagKeys into logical sets for UI organization.
• ID3FrameKey (base) — 80+ case enum for ID3v2.4 frame identifiers.
• InfoFrameKey (base) — 90+ case enum for RIFF INFO chunk tags.
• TagFrameKey (base) — Protocol providing default implementations for taglibKey, displayName, and init?(value:) shared by both frame key types.

• AudioFormatProperties (base) — Struct holding channel count, sample rate, bit depth, bit rate, and duration.
• AudioFormatProperties+IO (I/O) — Initializer from AVAudioFile.
• AudioFileType+TagType (I/O) — Bidirectional mapping between AudioFileType and TagFileTypeDef, with file extension, header inspection, and URL-based detection.
• BEXTDescription (base) — Broadcast Wave Extension (BWF) chunk wrapper supporting v0/v1/v2 fields including originator, coding history, UMID, loudness values, and 64-bit time reference.
• BEXTDescription+IO (I/O) — Read/write BEXT chunks via WaveFileC (TagLib). Conversion to/from the C bridge type BEXTDescriptionC.
• BEXTDescription+IXML (I/O) — Fallback BEXT construction from an iXML document for files that embed BEXT data in an iXML APPLICATION block rather than a binary BEXT chunk.
• BEXTDescription.Key (base) — Enum of BEXT field keys with OrderedDictionary subscript for dictionary-style get/set access.
• ImageDescription (base) — Embedded artwork container with CGImage, thumbnail generation, and Codable conformance.
• ImageDescription+IO (I/O) — Conversion to/from TagPictureRef for TagLib interop.
• WaveFileC+ (I/O) — Swift convenience accessors on WaveFileC for bextDescription, INFO frame subscripts, and ID3 frame subscripts.
• FlacFileC+ (I/O) — Swift convenience accessors on FlacFileC for bextDescription read/write via FLAC APPLICATION blocks.

Full structured support for the iXML (BWFXML) specification embedded in WAV and FLAC APPLICATION blocks. 56+ fields across 8 sections with round-trip XML fidelity.

• IXMLMetadata (I/O) — Core iXML document model covering production, speed, track list, loudness, BEXT mirror, history, user, ASWG, and location containers. Construct via init(xml:) to parse from an XML string, or init(from:) to build from a MetaAudioFileDescription. Generate XML via .xml.
• IXMLElement (I/O) — Type-safe enum of iXML element names with an AEXMLElement subscript extension for safe child access.
• IXMLTagDescriptor (I/O) — Field descriptor for UI editors: display name, section, XML tag, read-only status, and edit style (text/boolean/numeric/date). Registry of all 56+ fields queryable by section or identifier.
• IXMLSection (I/O) — Enum grouping iXML fields into UI sections: core, user, aswg, bext, speed, history, location, loudness.
• IXMLMetadata+Accessors (I/O) — Descriptor-based read/write via value(for:) and setValue(_:for:), enabling generic UI editors to access any iXML field without switch statements.
• IXMLUserFields (I/O) — Structured model for the 37-field Soundminer USER container. Parsed from and serialized back to the USER XML element with round-trip preservation of unknown fields.
• UCSUserFields (I/O) — UCS (Universal Category System) fields extracted from the USER element: CATEGORY, SUBCATEGORY, CATID. Auto-generates CATEGORYFULL on write.
• IXMLASWGFields (I/O) — 14-field structured model for the ASWG (Audio Software Group) container per the ASWG iXML spec.

• AudioMarkerDescription (base) — Format-agnostic marker struct with name, start/end time, color, and markerID. Codable, Comparable (by time, then name).
• AudioMarkerDescriptionCollection (base) — Ordered collection with insert, remove, update, sort, and automatic ID assignment.
• AudioMarkerDescription+IO (I/O) — Creates markers from Core Audio RIFF cue points.
• AudioMarkerDescriptionCollection+Parser (I/O) — Factory initializer from URL with automatic file-type dispatch to the appropriate parser.
• ChapterParser (I/O) — AVFoundation-based chapter parsing for M4A, MP4, FLAC, and OGG via AVAsset timed metadata.

Low-level bridge layer exposing TagLib functionality to Swift through Objective-C++ classes.

Add to your Package.swift:

.package(url: "https://github.com/ryanfrancesconi/spfk-metadata", from: "0.0.1")

Then import:

import SPFKMetadata          // Swift API + re-exported SPFKMetadataBase types
import SPFKMetadataC         // only needed for direct ObjC bridge access

Spongefork (SPFK) is the personal software projects of Ryan Francesconi. Dedicated to creative sound manipulation, his first application, Spongefork, was released in 1999 for macOS 8. From 2016 to 2025 he was the lead macOS developer at Audio Design Desk.