Inspired by this repo metadata reader SwiftTagLib

[Anywhere-Music-Player]

I've already asked about this here #362

Now its ready https://github.com/Anywhere-Music-Player/SwiftTagLib

Looks like this is what it should be? Could it be used with the engine?

[sbooth]

I'll check it out!

One thing I wonder about with Swift/C++ interoperability (especially in a library) is how to properly handle C++ exceptions. I recently added some exception-handling code in SFBAudioEngine but concern over C++ exceptions is what has really prevented me from adopting C++ interop in most of my projects.

[IgorMuzyka]

@sbooth i'm no expert in C++, i actually just looked at how you catch exceptions and decided to copy that to some extent.
here's an excerpt from AbstractAudioFile.hpp

try {
    ...
} catch (const std::runtime_error &error) {
    taglib_bridge_log(Error, "caught runtime error: %s", error.what());
    std::string message = error.what();
    errorDescription = &message;
    return MetadataReadingOutcome::runtimeError;
} catch (const std::exception &exception) {
    taglib_bridge_log(Error, "caught exception: %s", exception.what());
    std::string message = exception.what();
    errorDescription = &message;
    return MetadataReadingOutcome::exception;
} catch (...) {
    taglib_bridge_log(Error, "caught unknown exception");
    return MetadataReadingOutcome::unknownException;
}
return MetadataReadingOutcome::success;

[Anywhere-Music-Player]

@sbooth Stephen, I’ve added you as a collaborator since this is all based on your ideas and code. I hope we can collaborate! :)

[IgorMuzyka]

@sbooth feel free to ask me questions(while i haven't forgotten details of implementation lol).

Here's some difference from SFBAudioEngine and explanation of how things work.
Sorry for long read, this might as well be README.md, i tried to (over)explain things the best i can.
If you don't wanna read this just clone the repository and run test and see for yourself how it works.

taglib

taglib integrated directly as git submodule into it's own target also includes utfcpp as git submodule.

CxxTagLibBridge

• Instead of reading metadata into dictionary, for each kind of Tag in file a new instance of AudioMetadata is created from that Tag and then overlayed with void AudioMetadata::overlay(const AudioMetadata layer).
• AbstractAudioFile serves as generic interface for files requiring:
  • that FileType is a subclass of TagLib::File,
  • implementation for void read_metadata_implementation(FileType &file, AudioMetadata *metadata),
  • implementation for void write_metadata_implementation(FileType &file, AudioMetadata *metadata).

  this allows for somewhat streamlined and simple implementation of each AudioFile itself, while the interface exposed to Swift looks like this:

  • MetadataReadingOutcome readMetadata(AudioMetadata *metadata, AudioProperties *properties, std::string *errorDescription)
  • MetadataWritingOutcome writeMetadata(AudioMetadata *metadata, std::string *errorDescription)
• AudioFile.hpp is just and import umbrella for audio file implementations (all of them are struct's):
  • AIFF.hpp, DSDIFF.hpp, DSF.hpp, FLAC.hpp, MP3.hpp, MP4.hpp, MonkeyAudio.hpp, Musepack.hpp, OggFLAC.hpp, OggOpus.hpp, OggSpeex.hpp, OggVorbis.hpp, TrueAudio.hpp, WAVE.hpp, WavPack.hpp.
• AudioFile aside from field also holds using AttachedPictures = std::vector<Picture> and using AdditionalMetadataPair = std::pair<std::string, std::string>.
• Interaction with Tag's happens much alike in SFBAudioEngine in categories on AudioMetadata:
  • AudioMetadata+AbstractTag.cpp
  • AudioMetadata+ID3v1Tag.cpp
  • AudioMetadata+D3v2Tag.cpp
  • AudioMetadata+MP4Tag.cpp
  • AudioMetadata+APETag.cpp
  • AudioMetadata+XIPHComment.cpp
• The AudioMetadata.Picture also has bunch of categories for converting images:
  • AudioMetadata.Picture+ImageIO.cpp
  • AudioMetadata.Picture+convert_to.cpp
  • AudioMetadata.Picture+create_from.cpp

SwiftTagLib

• On the Swift side of things AudioFileImplementation serves as common interface for all those audio files which inherit from AbstractAudioFile.hpp in CxxTagLibBridge and conformances are defined after the fact.

protocol AudioFileImplementation {
    init(_ fileName: std.string)

    func readMetadata(
        _ metadata: UnsafeMutablePointer<AudioMetadata>!,
        _ properties: UnsafeMutablePointer<AudioProperties>!,
        _ errorDescription: UnsafeMutablePointer<std.string>!
    ) -> MetadataReadingOutcome

    func writeMetadata(
        _ metadata: UnsafeMutablePointer<AudioMetadata>!,
        _ errorDescription: UnsafeMutablePointer<std.string>!
    ) -> MetadataWritingOutcome
}

• AudioFile.Properties is a Swift equivalent of AudioProperties.hpp.
• AudioFile.Metadata is a Swift equivalent of AudioMetadata.hpp.
• AudioFile.Metadata.AttachedPicture.hpp is Swift equivalent of AudioMetadata.Picture.
• AudioFile.Metadata.AdditionalMetadataPair is Swift equivalent of using AdditionalMetadataPair = std::pair<std::string, std::string>.

All of the equivalent types in Swift conform to CxxRepresentable protocol:

protocol CxxRepresentable {
    associatedtype CxxRepresentation
    init(cxxRepresentation: CxxRepresentation)
    var cxxRepresentation: CxxRepresentation { get }
}

AudioMetadata.hpp also stores a bitmask of it's TagSource with Swift equivalent OptionSet TagSource.

TagSource was quite useful during testing to understand the common errors when reading from or writing to Tag's.

Format detection is done only in Swift as this doesn't really touch taglib or require Objective-C or C++.
There's AudioFile protocol:

protocol AudioFormat {
    static var supportedPathExtensions: Set<String> { get }
    static var supportedMIMETypes: Set<String> { get }
    static func isFormatSupported(_ fileHandle: FileHandle) -> Bool

    /// import escaping.
    typealias ImplementationClass = CxxTagLibBridge.AudioFile
    associatedtype Implementation: AudioFileImplementation
}

extension AudioFormat {
    static var implementationMetatype: Implementation.Type { Implementation.self }
}

And AudioFile.Format enum which provides us with:

var formatMetatype: any AudioFormat.Type { ... }
var implementationMetatype: AudioFileImplementation.Type { formatMetatype.implementationMetatype }

The detection of format is done much alike in SFBAudioEngine by calculating the score for each one in AudioFile.Format.Detector.

There's just 3 types protocols for file header format/layout defined: BasicHeader Layout/Format, CompositeHeader Layout/Format and CustomHeader Layout/Format.

There's also two helper structs for this to work:

• BinaryData struct to read UTF8 String's easily from data obtained from FileHandle.
• ID3v2ShallowHeader to check for ID3v2, this mostly exact copy from SFBAudioEngine but done in Swift.

File header format/layout by categories:

• BasicHeader:
  • FLAC.swift
  • MP4.swift
  • MonkeyAudio.swift
  • TrueAudio.swift
  • WavPack.swift
• CompositeHeader:
  • AIFF.swift
  • DSDIFF.swift
  • DSF.swift
  • OggFLAC.swift
  • OggOpus.swift
  • OggSpeex.swift
  • OggVorbis.swift
  • WAVE.swift
• CustomHeader:
  • MP3.swift
  • Musepack.swift

Tests

There's some audio file samples in repository and Tests are executed using them.

• LanguageBarrierTraversalTest.swift is a suite of a sanity checks that we can go from Swift to C++ type and back and it behaves as expected.
• AudioFileTests.swift is a suite of test check that interaction operations with metadata behave as expected with some caveats.
  • Reading metadata expects that metadata read from file doesn't differ between reads.
  • Same self overwrite expects that writing metadata read from file to copy of that file produces same metadata when read again after writing.
  • Writing metadata expects that semi-random metadata is written to file when read again after writing.
  • Erasing metadata expects that erased metadata isn't there when read again after writing.

Here's a caveat:

for keyPath in Self.stringProperties {
    let string = UUID().uuidString.replacingOccurrences(of: "-", with: "")
    /// ID3v1 imposes 128 bytes limitation on fields
    /// which is 30 characters: or approximately 28 ASCII characters + 2 bytes of language code.
    /// Going over this character limit currently only fails test for mp3 file,
    /// indicating the limit depends on actual format implementation
    metadata[keyPath: keyPath] = String(string.prefix(28))
}

Not everything is reproduced and there's some performance caveats

• There's one ugly problem i encountered and rather than solved just worked around it;
  • going from Swift.Array<T> to std::vector<T> and vice versa, here and here, i actually created an Issue for that .

  it can be improved but this will introduce some use of unsafe pointers, and i'm quite unsure what's worse unsafe memory access in between Swift and C++ or slowly building up a std::vector in loop via push_back method.

• Not all metadata fields are covered/supported, i ignored supporting ReplayGain and Sorting/Grouping metadata entries as they weren't crucial for @Volodymyr-13 , here's the Issue for that.

[Anywhere-Music-Player]

@sbooth Stephen, I hope such detailed readme won't scare you, lol.
More details, less questions :D

[sbooth]

More details, less questions

I agree!

[Anywhere-Music-Player]

@sbooth

Hi, we’ve fixed the issues related to differences with SFBAudioEngine:
Anywhere-Music-Player/SwiftTagLib#3

Now, I believe SwiftTagLib is nearly ready for production use.

p.s. SFBAudioEngine had some bugs with reading the comments tag. I’m not sure if they’ve been fixed in the latest versions, as I was using it only up to 0.5.0.

[Anywhere-Music-Player]

@sbooth SwiftTagLib is now listed on https://taglib.org/#language-bindings.

It’s still not a 1-to-1 replacement for SFBAudioEngine’s metadata reader (by the way, during testing we found that some metadata fields are read incorrectly or are missing).

Would you consider becoming a contributor to SwiftTagLib?

taglib/taglib#1272 (comment)