source: project/wiki/eggref/5/taglib @ 37607

Last change on this file since 37607 was 37607, checked in by wasamasa, 17 months ago

taglib: Add documentation

File size: 7.1 KB
Line 
1== taglib
2
3[[toc:]]
4
5=== Introduction
6
7This egg provides a usable subset of bindings to the
8[[https://taglib.org/|taglib]] library.
9
10=== Author
11
12Vasilij Schneidermann
13
14=== Repository
15
16[[https://github.com/wasamasa/taglib]]
17
18=== Current state of the bindings
19
20The egg does intentionally not use taglib's C API as is due to
21incompatibilities with the CHICKEN FFI.  For this reason the bindings
22are modeled after its C API with the following differences:
23
24* Only UTF-8 strings are supported, there is no flag to switch between
25  UTF-8 and Latin-1
26* Memory management immediately frees strings, there is no option to
27  defer garbage collection of strings
28* The API exclusively operates on {{TagLib::File}} instances,
29  represented as {{taglib-file}} records
30* The raw tag property API is supported in addition to the audio
31  property and tag property API, it permits retrieving and setting
32  more than the standard set of tag properties
33
34=== Requirements
35
36Install the taglib library with your operating system's package
37manager.
38
39=== API
40
41Note that due to pervasive use of {{and-let*}} all API calls will
42return {{#f}} if the {{FILE}} argument's resources have been freed.
43
44==== File management
45
46===== file-open
47
48<procedure>(file-open PATH)</procedure>
49
50Opens an audio file the {{PATH}} string points to.  If successful, a
51{{taglib-file}} record is returned which is used in all subsequent API
52calls, otherwise {{#f}}.
53
54===== file-valid?
55
56<procedure>(file-valid? FILE)</procedure>
57
58Returns {{#t}} if {{FILE}} is a {{taglib-file}} record and readable,
59otherwise {{#f}}.
60
61===== file-save!
62
63<procedure>(file-save! FILE)</procedure>
64
65Stores changes made by the setter procedures to the file backing
66{{FILE}}.
67
68===== file-free!
69
70<procedure>(file-free! FILE)</procedure>
71
72Frees the resources associated with {{FILE}} if any.  This procedure
73is used as finalizer for {{taglib-file}} records, therefore it's not
74necessary to call it manually, but can be done anyway.
75
76==== Audio properties
77
78===== audio-property
79
80<procedure>(audio-property FILE KEY)</procedure>
81
82Returns an audio property for {{FILE}}, either a number or {{#f}} if
83it couldn't be detected.  {{KEY}} must be one of the following
84symbols:
85
86; {{length}} : Length in seconds with millisecond precision
87; {{bitrate}} : Bit rate in kb/s
88; {{samplerate}} : Sample rate in Hz
89; {{channels}} : Number of channels
90
91===== audio-properties
92
93<procedure>(audio-properties FILE)</procedure>
94
95Returns an alist of all audio properties for {{FILE}}.  The keys are
96{{(length bitrate samplerate channels)}}, the values are the same as
97if obtained by using {{audio-property}}.
98
99==== Tag properties
100
101===== tag-property / tag-property-set!
102
103<procedure>(tag-property FILE KEY)</procedure>
104<procedure>(tag-property-set! FILE KEY VALUE)</procedure>
105<setter>(set! (tag-property FILE KEY) VALUE)</setter>
106
107Returns or sets a tag property for {{FILE}}.  {{KEY}} must be one of
108the following symbols:
109
110; {{title}} : Title (string)
111; {{artist}} : Artist (string)
112; {{album}} : Album (string)
113; {{comment}} : Comment (string)
114; {{genre}} : Genre (string)
115; {{year}} : Year (number)
116; {{track}} : Track (number)
117
118A return value of {{#f}} indicates an unset property.  Likewise {{#f}}
119can be used as {{VALUE}} to clear a property.
120
121===== tag-properties
122
123<procedure>(tag-properties FILE)</procedure>
124
125Returns an alist of all tag properties for {{FILE}}.  The keys are
126{{(title artist album comment genre year track)}}, the values the same
127as if obtained by using {{tag-property}}.
128
129==== Raw tag properties
130
131===== raw-tag-property-exists?
132
133<procedure>(raw-tag-property-exists? FILE KEY)</procedure>
134
135Returns {{#t}} if {{FILE}} contains the raw tag property {{KEY}},
136otherwise {{#f}}.  {{KEY}} must be a string.
137
138===== raw-tag-property / raw-tag-property-set!
139
140<procedure>(raw-tag-property FILE KEY)</procedure>
141<procedure>(raw-tag-property-set! FILE KEY VALUES)</procedure>
142<setter>(set! (raw-tag-property FILE KEY) VALUES)</setter>
143
144Returns or sets a list of string values in {{FILE}} for the raw tag
145property {{KEY}}.  {{KEY}} must be a string.  {{VALUES}} is a list of
146strings.  An unset property is represented as the empty list.
147
148===== raw-tag-property-clear!
149
150<procedure>(raw-tag-property-clear! FILE KEY)</procedure>
151
152Clears the raw tag property in {{FILE}} for {{KEY}}.  {{KEY}} must be
153a string.
154
155===== raw-tag-properties / raw-tag-properties-set!
156
157<procedure>(raw-tag-properties FILE)</procedure>
158<procedure>(raw-tag-properties-set! FILE PROPERTIES)</procedure>
159<setter>(set! (raw-tag-properties FILE) PROPERTIES)</setter>
160
161Returns or sets an alist of raw tag properties for {{FILE}}.
162{{PROPERTIES}} is an alist where each key is a string and each value a
163non-empty list of strings.
164
165=== Examples
166
167<enscript highlight="scheme">
168(import scheme)
169(import (chicken base))
170(import (chicken pretty-print))
171(import (chicken process-context))
172(import (chicken string))
173(import (prefix taglib taglib:))
174
175(define (with-unit value unit)
176  (if value
177      (string-append (->string value) unit)
178      "unknown"))
179
180(define (inexact arg)
181  (and (number? arg) (exact->inexact arg)))
182
183(for-each
184 (lambda (path)
185   (let ((file (taglib:file-open path)))
186     (when (and file (taglib:file-valid? file))
187       (print "Processing: " path "...")
188       (print "Length: " (with-unit (inexact (taglib:audio-property file 'length)) "s"))
189       (print "Bitrate: " (with-unit (taglib:audio-property file 'bitrate) "kb/s"))
190       (print "Samplerate: " (with-unit (taglib:audio-property file 'samplerate) "Hz"))
191       (print "Channels: " (or (taglib:audio-property file 'channels) "unknown"))
192       (print "Title: " (or (taglib:tag-property file 'title) "unknown"))
193       (print "Artist: " (or (taglib:tag-property file 'artist) "unknown"))
194       (print "Album: " (or (taglib:tag-property file 'album) "unknown"))
195       (print "Comment: " (or (taglib:tag-property file 'comment) "unknown"))
196       (print "Genre: " (or (taglib:tag-property file 'genre) "unknown"))
197       (print "Year: " (or (taglib:tag-property file 'year) "unknown"))
198       (print "Track: " (or (taglib:tag-property file 'track) "unknown"))
199       (for-each
200        (lambda (property)
201          (let ((key (car property))
202                (values (cdr property)))
203            (print key ": " (string-intersperse values ","))))
204        (taglib:raw-tag-properties file)))))
205 (command-line-arguments))
206</enscript>
207
208Further examples can be found
209[[https://github.com/wasamasa/taglib/tree/master/examples|in the
210repository]].
211
212=== License
213
214 Copyright 2019 Vasilij Schneidermann
215 
216 This library is free software; you can redistribute it and/or
217 modify it under the terms of the GNU Lesser General Public
218 License as published by the Free Software Foundation; either
219 version 2.1 of the License, or (at your option) any later version.
220 
221 This library is distributed in the hope that it will be useful,
222 but WITHOUT ANY WARRANTY; without even the implied warranty of
223 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
224 Lesser General Public License for more details.
225 
226 You should have received a copy of the GNU Lesser General Public
227 License along with this library; if not, write to the Free Software
228 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
229
230=== Version history
231
232==== 0.1
233
234* Initial release
Note: See TracBrowser for help on using the repository browser.