taglib

  1. taglib
    1. Introduction
    2. Author
    3. Repository
    4. Current state of the bindings
    5. Requirements
    6. API
      1. File management
        1. file-open
        2. file-valid?
        3. file-save!
        4. file-free!
      2. Audio properties
        1. audio-property
        2. audio-properties
      3. Tag properties
        1. tag-property / tag-property-set!
        2. tag-properties
      4. Raw tag properties
        1. raw-tag-property-exists?
        2. raw-tag-property / raw-tag-property-set!
        3. raw-tag-property-clear!
        4. raw-tag-properties / raw-tag-properties-set!
    7. Examples
    8. License
    9. Version history
      1. 0.1

Introduction

This egg provides a usable subset of bindings to the taglib library.

Author

Vasilij Schneidermann

Repository

https://github.com/wasamasa/taglib

Current state of the bindings

The egg does intentionally not use taglib's C API as is due to incompatibilities with the CHICKEN FFI. For this reason the bindings are modeled after its C API with the following differences:

Requirements

Install the taglib library with your operating system's package manager.

API

Note that due to pervasive use of and-let* all API calls will return #f if the FILE argument's resources have been freed.

File management

file-open
[procedure] (file-open PATH)

Opens an audio file the PATH string points to. If successful, a taglib-file record is returned which is used in all subsequent API calls, otherwise #f.

file-valid?
[procedure] (file-valid? FILE)

Returns #t if FILE is a taglib-file record and readable, otherwise #f.

file-save!
[procedure] (file-save! FILE)

Stores changes made by the setter procedures to the file backing FILE.

file-free!
[procedure] (file-free! FILE)

Frees the resources associated with FILE if any. This procedure is used as finalizer for taglib-file records, therefore it's not necessary to call it manually, but can be done anyway.

Audio properties

audio-property
[procedure] (audio-property FILE KEY)

Returns an audio property for FILE, either a number or #f if it couldn't be detected. KEY must be one of the following symbols:

length
Length in seconds with millisecond precision
bitrate
Bit rate in kb/s
samplerate
Sample rate in Hz
channels
Number of channels
audio-properties
[procedure] (audio-properties FILE)

Returns an alist of all audio properties for FILE. The keys are (length bitrate samplerate channels), the values are the same as if obtained by using audio-property.

Tag properties

tag-property / tag-property-set!
[procedure] (tag-property FILE KEY)
[procedure] (tag-property-set! FILE KEY VALUE)
[setter] (set! (tag-property FILE KEY) VALUE)

Returns or sets a tag property for FILE. KEY must be one of the following symbols:

title
Title (string)
artist
Artist (string)
album
Album (string)
comment
Comment (string)
genre
Genre (string)
year
Year (number)
track
Track (number)

A return value of #f indicates an unset property. Likewise #f can be used as VALUE to clear a property.

tag-properties
[procedure] (tag-properties FILE)

Returns an alist of all tag properties for FILE. The keys are (title artist album comment genre year track), the values the same as if obtained by using tag-property.

Raw tag properties

raw-tag-property-exists?
[procedure] (raw-tag-property-exists? FILE KEY)

Returns #t if FILE contains the raw tag property KEY, otherwise #f. KEY must be a string.

raw-tag-property / raw-tag-property-set!
[procedure] (raw-tag-property FILE KEY)
[procedure] (raw-tag-property-set! FILE KEY VALUES)
[setter] (set! (raw-tag-property FILE KEY) VALUES)

Returns or sets a list of string values in FILE for the raw tag property KEY. KEY must be a string. VALUES is a list of strings. An unset property is represented as the empty list.

raw-tag-property-clear!
[procedure] (raw-tag-property-clear! FILE KEY)

Clears the raw tag property in FILE for KEY. KEY must be a string.

raw-tag-properties / raw-tag-properties-set!
[procedure] (raw-tag-properties FILE)
[procedure] (raw-tag-properties-set! FILE PROPERTIES)
[setter] (set! (raw-tag-properties FILE) PROPERTIES)

Returns or sets an alist of raw tag properties for FILE. PROPERTIES is an alist where each key is a string and each value a non-empty list of strings.

Examples

(import scheme)
(import (chicken base))
(import (chicken pretty-print))
(import (chicken process-context))
(import (chicken string))
(import (prefix taglib taglib:))

(define (with-unit value unit)
  (if value
      (string-append (->string value) unit)
      "unknown"))

(define (inexact arg)
  (and (number? arg) (exact->inexact arg)))

(for-each
 (lambda (path)
   (let ((file (taglib:file-open path)))
     (when (and file (taglib:file-valid? file))
       (print "Processing: " path "...")
       (print "Length: " (with-unit (inexact (taglib:audio-property file 'length)) "s"))
       (print "Bitrate: " (with-unit (taglib:audio-property file 'bitrate) "kb/s"))
       (print "Samplerate: " (with-unit (taglib:audio-property file 'samplerate) "Hz"))
       (print "Channels: " (or (taglib:audio-property file 'channels) "unknown"))
       (print "Title: " (or (taglib:tag-property file 'title) "unknown"))
       (print "Artist: " (or (taglib:tag-property file 'artist) "unknown"))
       (print "Album: " (or (taglib:tag-property file 'album) "unknown"))
       (print "Comment: " (or (taglib:tag-property file 'comment) "unknown"))
       (print "Genre: " (or (taglib:tag-property file 'genre) "unknown"))
       (print "Year: " (or (taglib:tag-property file 'year) "unknown"))
       (print "Track: " (or (taglib:tag-property file 'track) "unknown"))
       (for-each
        (lambda (property)
          (let ((key (car property))
                (values (cdr property)))
            (print key ": " (string-intersperse values ","))))
        (taglib:raw-tag-properties file)))))
 (command-line-arguments))

Further examples can be found in the repository.

License

Copyright 2019 Vasilij Schneidermann

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Version history

0.1