4.1 Opening and closing tag handles🔗ℹ

In read-write mode, the native TagLib file remains open. Setter procedures may then be used to modify fields, properties, and pictures. Call tags-save! to write changes and tags-close! to close the native handle.

On Windows, the implementation retries with the wide-character TagLib open function when the normal open function does not produce a valid TagLib file.

(call-with-id3-tags "track.flac"

(lambda (tags)

(when (tags-valid? tags)

(tags-title! tags "New title")

(tags-save! tags)))

#:mode 'read-write)

4.2 Common tag fields🔗ℹ

4.3 Selected generic fields🔗ℹ

4.4 Audio properties🔗ℹ

4.5 Generic properties🔗ℹ

(call-with-id3-tags "track.flac"

(lambda (tags)

(tags-set-values! tags 'composer '("Johann Sebastian Bach"))

(tags-set! tags 'discnumber "1")

(tags-save! tags))

#:mode 'read-write)

Generic properties may contain multiple values for a single key. The API keeps those values as lists instead of joining them into one string.

4.6 Embedded pictures🔗ℹ

The module represents embedded artwork as an opaque picture value. The picture value is returned by tags-picture and can be inspected with the picture procedures documented below. It can also be written to another file with tags-picture! or tags-append-picture!.

(define cover

(make-tags-picture "image/jpeg" 3 (file->bytes "cover.jpg")

#:description "Cover"))

(call-with-id3-tags "track.flac"

(lambda (tags)

(tags-picture! tags cover)

(tags-save! tags))

#:mode 'read-write)

4.7 Picture values🔗ℹ

4.8 Converting to a hash🔗ℹ

The hash is intended as a convenient snapshot for application code. Generic property values are not expanded into the hash; use tags-ref for those values.

4.9 Copying tags and pictures🔗ℹ

The encoder pipeline uses this module for metadata transfer. For FLAC output, audio-encode first writes the audio stream and then opens the resulting file with id3-tags in read-write mode to copy tags and pictures through TagLib. For Opus output, comments and pictures are supplied to libopusenc before encoding starts, because OpusTags are written at the start of the Ogg Opus stream.

Applications that need explicit metadata editing should use the read-write API directly, as in the examples above.

4.10 Example🔗ℹ

(define tags (id3-tags "track.flac"))

(cond

[(not (tags-valid? tags))

(printf "No readable tags\n")]

[else

(printf "Title:  ~a\n" (tags-title tags))

(printf "Artist: ~a\n" (tags-artist tags))

(printf "Album:  ~a\n" (tags-album tags))

(printf "Length: ~a seconds\n" (tags-length tags))

(when (tags-picture tags)

(define ext (or (tags-picture->ext tags) 'bin))

(tags-picture->file tags (format "cover.~a" ext)))])

4.11 Implementation notes🔗ℹ

This chapter documents the public "taglib.rkt" layer. The native TagLib calls are delegated to "taglib-ffi.rkt", but callers normally should not use that lower level module directly.

A read-only tag handle is a Racket-side snapshot. A read-write tag handle keeps the native TagLib file open until tags-close! is called. Setter procedures update both the native file and the Racket-side cache; the changes are persisted only after tags-save! succeeds.

The implementation normalizes generic property names by lower-casing TagLib property keys and converting them to symbols. Values remain lists of strings because TagLib properties may contain multiple values for one key.