File: README.md

package info (click to toggle)
node-groove 2.5.0-2
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 348 kB
  • ctags: 331
  • sloc: cpp: 1,953; makefile: 19
file content (552 lines) | stat: -rw-r--r-- 13,712 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
# node-groove

Node.js bindings to [libgroove](https://github.com/andrewrk/libgroove) -
generic music player backend library.

Live discussion in `#libgroove` on [freenode](https://freenode.net/).

## Usage

1. Install libgroove to your system. libgroove is a set of 4 libraries;
   node-groove depends on all of them. So for example on ubuntu, make sure to
   install libgroove-dev, libgrooveplayer-dev, libgrooveloudness-dev, and
   libgroovefingerprinter-dev.
2. `npm install --save groove`

### Versions

 * node-groove >=2.4.0 depends on libgroove >=4.3.0
 * use node-groove 2.3.4 if you want to use libgroove <4.3.0

### Get Metadata from File

```js
var groove = require('groove');

groove.open("danse-macabre.ogg", function(err, file) {
  if (err) throw err;
  console.log(file.metadata());
  console.log("duration:", file.duration());
  file.close(function(err) {
    if (err) throw err;
  });
});
```

#### More Examples

 * example/metadata.js - read or update metadata in a media file
 * example/playlist.js - play several files in a row and then exit
 * example/replaygain.js - compute replaygain values for media files
 * example/transcode.js - convert and splice several files together
 * example/fingerprint.js - create an acoustid fingerprint for media files

## API Documentation

### globals

#### groove.setLogging(level)

`level` can be:

 * `groove.LOG_QUIET`
 * `groove.LOG_ERROR`
 * `groove.LOG_WARNING`
 * `groove.LOG_INFO`

#### groove.loudnessToReplayGain(loudness)

Converts a loudness value which is in LUFS to the ReplayGain-suggested dB
adjustment.

#### groove.dBToFloat(dB)

Converts dB format volume adjustment to a floating point gain format.

#### groove.getVersion()

Returns an object with these properties:

 * `major`
 * `minor`
 * `patch`

### GrooveFile

#### groove.open(filename, callback)

`callback(err, file)`

#### file.close(callback)

`callback(err)`

#### file.duration()

In seconds.

#### file.shortNames()

A comma-separated list of short names for the format.

#### file.getMetadata(key, [flags])

Flags:

 * `groove.TAG_MATCH_CASE`
 * `groove.TAG_DONT_OVERWRITE`
 * `groove.TAG_APPEND`

#### file.setMetadata(key, value, [flags])

See `getMetadata` for flags.

Pass `null` for `value` to delete a key.

#### file.metadata()

This returns an object populated with all the metadata.
Updating the object does nothing. Use `setMetadata` to
update metadata and then `save` to write changes to disk.

#### file.dirty

Boolean whether `save` will do anything.

#### file.filename

The string that was passed to `groove.open`

#### file.save(callback)

`callback(err)`

### GroovePlaylist

#### groove.createPlaylist()

A playlist managers keeping an audio buffer full. To send the buffer
to your speakers, use `playlist.createPlayer()`.

#### playlist.items()

Returns a read-only array of playlist items.
Use `playlist.insert` and `playlist.remove` to modify.

`[playlistItem1, playlistItem2, ...]`

#### playlist.play()

#### playlist.pause()

#### playlist.seek(playlistItem, position)

Seek to `playlistItem`, `position` seconds into the song.

#### playlist.insert(file, gain, peak, nextPlaylistItem)

Creates a new playlist item with file and puts it in the playlist before
`nextPlaylistItem`. If `nextPlaylistItem` is `null`, appends the new
item to the playlist.

`gain` is a float format volume adjustment that applies only to this item.
defaults to 1.0

`peak` is float format, see `item.peak`.
defaults to 1.0

Returns the newly added playlist item.

Once you add a file to the playlist, you must not `file.close()` it until
you first remove it from the playlist.

#### playlist.remove(playlistItem)

Remove `playlistItem` from the playlist.

Note that you are responsible for calling `file.close()` on every file
that you open with `groove.open`. `playlist.remove` will not close files.

#### playlist.position()

Returns `{item, pos}` where `item` is the playlist item currently being
decoded and `pos` is how many seconds into the song the decode head is.

Note that typically you are more interested in the position of the play head,
not the decode head. Example methods which return the play head are
`player.position()` and `encoder.position()`.

#### playlist.playing()

Returns `true` or `false`.

#### playlist.clear()

Remove all playlist items.

#### playlist.count()

How many items are on the playlist.

#### playlist.gain

#### playlist.setGain(value)

Between 0.0 and 1.0. You probably want to leave this at 1.0, since using
replaygain will typically lower your volume a significant amount.

#### playlist.setItemGain(playlistItem, gain)

`gain` is a float that affects the volume of the specified playlist item only.
To convert from dB to float, use exp(log(10) * 0.05 * dBValue).

#### playlist.setItemPeak(playlistItem, peak)

See `item.peak`

#### playlist.setFillMode(mode)

`mode` can be:

 * `groove.EVERY_SINK_FULL`

    This is the default behavior. The playlist will decode audio if any sinks
    are not full. If any sinks do not drain fast enough the data will buffer up
    in the playlist.

 * `groove.ANY_SINK_FULL`

    With this behavior, the playlist will stop decoding audio when any attached
    sink is full, and then resume decoding audio every sink is not full.

Defaults to `groove.EVERY_SINK_FULL`.

### GroovePlaylistItem

These are not instantiated directly; instead they are returned from
`playlist.items()`.

#### item.file

Read-only.

#### item.gain

A volume adjustment in float format to apply to the file when it plays.
This is typically used for loudness compensation, for example ReplayGain.
To convert from dB to float, use `groove.dBToFloat`

Read-only. Use `playlist.setItemGain` to modify.

#### item.peak

The sample peak of this playlist item is assumed to be 1.0 in float
format. If you know for certain that the peak is less than 1.0, you
may set this value which may allow the volume adjustment to use
a pure amplifier rather than a compressor. This results in slightly
better audio quality.

Read-only. Use `playlist.setItemPeak` to modify.

#### item.id

Every time you obtain a playlist item from groove, you will get a fresh
JavaScript object, but it might point to the same underlying libgroove pointer
as another. The `id` field is a way to check if two playlist items reference
the same one.

Read-only.

### GroovePlayer

#### groove.getDevices()

Returns an array of device names which are the devices you can send audio
to.

#### groove.createPlayer()

Creates a GroovePlayer instance which you can then configure by setting
properties.

#### player.deviceIndex

Before calling `attach()`, set this to the index of one of the devices
returned from `groove.getDevices()` or `null` to represent the default device.
Use `groove.DUMMY_DEVICE` to represent a dummy audio player.

#### player.targetAudioFormat

The desired audio format settings with which to open the device.
`groove.createPlayer()` defaults these to 44100 Hz,
signed 16-bit int, stereo.
These are preferences; if a setting cannot be used, a substitute will
be used instead. In this case, actualAudioFormat will be updated to reflect
the substituted values.

Properties:

 * `sampleRate`
 * `channelLayout`
 * `sampleFormat`

#### player.actualAudioFormat

groove sets this to the actual format you get when you open the device.
Ideally will be the same as targetAudioFormat but might not be.

Properties:

 * `sampleRate`
 * `channelLayout`
 * `sampleFormat`

#### player.deviceBufferSize

how big the device buffer should be, in sample frames.
must be a power of 2.
`groove.createPlayer()` defaults this to 1024

#### player.sinkBufferSize

How big the sink buffer should be, in sample frames.
`groove.createPlayer()` defaults this to 8192

#### player.useExactAudioFormat

If you set this to `true`, `targetAudioFormat` and `actualAudioFormat` are
ignored and no resampling, channel layout remapping, or sample format
conversion will occur. The audio device will be reopened with exact parameters
whenever necessary.

#### player.attach(playlist, callback)

Sends audio to sound device.

`callback(err)`

#### player.detach(callback)

`callback(err)`

#### player.position()

Returns `{item, pos}` where `item` is the playlist item currently being
played and `pos` is how many seconds into the song the play head is.

#### player.on('nowplaying', handler)

Fires when the item that is now playing changes. It can be `null`.

`handler()`

#### player.on('bufferunderrun', handler)

Fires when a buffer underrun occurs. Ideally you'll never see this.

`handler()`

#### player.on('devicereopened', handler)

Fires when you have set `useExactAudioFormat` to `true` and the audio device
has been closed and re-opened to match incoming audio data.

`handler()`

### GrooveEncoder

#### groove.createEncoder()

#### encoder.bitRate

select encoding quality by choosing a target bit rate

#### encoder.formatShortName

optional - help libgroove guess which format to use.
`avconv -formats` to get a list of possibilities.

#### encoder.codecShortName

optional - help libgroove guess which codec to use.
`avconv-codecs` to get a list of possibilities.

#### encoder.filename

optional - provide an example filename to help libgroove guess
which format/codec to use.

#### encoder.mimeType

optional - provide a mime type string to help libgrooove guess
which format/codec to use.

#### encoder.targetAudioFormat

The desired audio format settings with which to encode.
`groove.createEncoder()` defaults these to 44100 Hz,
signed 16-bit int, stereo.
These are preferences; if a setting cannot be used, a substitute will
be used instead. In this case, actualAudioFormat will be updated to reflect
the substituted values.

Properties:

 * `sampleRate`
 * `channelLayout`
 * `sampleFormat`

#### encoder.actualAudioFormat

groove sets this to the actual format you get when you attach the encoder.
Ideally will be the same as targetAudioFormat but might not be.

Properties:

 * `sampleRate`
 * `channelLayout`
 * `sampleFormat`

#### encoder.sinkBufferSize

How big the sink buffer should be, in sample frames.
`createEncoder` defaults this to 8192

#### encoder.encodedBufferSize

How big the encoded audio buffer should be, in bytes.
`createEncoder` defaults this to 16384

#### encoder.attach(playlist, callback)

`callback(err)`

#### encoder.detach(callback)

`callback(err)`

#### encoder.getBuffer()

Returns `null` if no buffer available, or an object with these properties:

 * `buffer` - a node `Buffer` instance which is the encoded data for this chunk
   this can be `null` in which case this buffer is actually the end of
   playlist sentinel.
 * `item` - the GroovePlaylistItem of which this buffer is encoded data for
 * `pos` - position in seconds that this buffer represents in into the item

#### encoder.on('buffer', handler)

`handler()`

Emitted when there is a buffer available to get. You still need to get the
buffer with `getBuffer()`.

#### encoder.position()

Returns `{item, pos}` where `item` is the playlist item currently being
encoded and `pos` is how many seconds into the song the encode head is.

### GrooveLoudnessDetector

#### groove.createLoudnessDetector()

returns a GrooveLoudnessDetector

#### detector.infoQueueSize

Set this to determine how far ahead into the playlist to look.

#### detector.sinkBufferSize

How big the sink buffer should be, in sample frames.
`groove.createLoudnessDetector()` defaults this to 8192

#### detector.disableAlbum

Set to `true` to only compute track loudness. This is faster and requires less
memory than computing both.

#### detector.attach(playlist, callback)

`callback(err)`

#### detector.detach(callback)

`callback(err)`

#### detector.getInfo()

Returns `null` if no info available, or an object with these properties:

 * `loudness` - loudness in LUFS
 * `peak` - sample peak in float format of the file
 * `duration` - duration in seconds of the track
 * `item` - the GroovePlaylistItem that this applies to, or `null` if it applies
   to the entire album.

#### detector.position()

Returns `{item, pos}` where `item` is the playlist item currently being
detected and `pos` is how many seconds into the song the detect head is.

#### detector.on('info', handler)

`handler()`

Emitted when there is info available to get. You still need to get the info
with `getInfo()`.

### GrooveFingerprinter

#### groove.createFingerprinter()

returns a GrooveFingerprinter

#### groove.encodeFingerprint(rawFingerprint)

Given an Array of integers which is the raw fingerprint, encode it into a
string which can be submitted to acoustid.org.

#### groove.decodeFingerprint(fingerprint)

Given the fingerprint string, returns a list of integers which is the raw
fingerprint data.

#### printer.infoQueueSize

Set this to determine how far ahead into the playlist to look.

#### printer.sinkBufferSize

How big the sink buffer should be, in sample frames.
`groove.createFingerprinter()` defaults this to 8192

#### printer.attach(playlist, callback)

`callback(err)`

#### printer.detach(callback)

`callback(err)`

#### printer.getInfo()

Returns `null` if no info available, or an object with these properties:

 * `fingerprint` - integer array which is the raw fingerprint
 * `duration` - duration in seconds of the track
 * `item` - the GroovePlaylistItem that this applies to, or `null` if it applies
   to the entire album.

#### printer.position()

Returns `{item, pos}` where `item` is the playlist item currently being
fingerprinted and `pos` is how many seconds into the song the printer head is.

#### printer.on('info', handler)

`handler()`

Emitted when there is info available to get. You still need to get the info
with `getInfo()`.