mpd2
Version:
Music Player Daemon client
277 lines (188 loc) • 7.26 kB
Markdown
Connect to a [Music Player Daemon](https://musicpd.org) ([GIT](https://github.com/MusicPlayerDaemon/MPD)) server, send commands, emit events.
This is a rewrite of [mpd.js module](https://github.com/andrewrk/mpd.js) to promise based methods and support for parsing of various MPD responses.
For higher level API module check out [mpd-api](https://github.com/cotko/mpd-api).
```
npm i / yarn mpd2
```
```js
const mpd = require('mpd2')
const { cmd } = mpd
// config is passed to net.connect()
const config = {
host: 'localhost',
port: 6600,
// if connecting to a local socket rather than
// host and port; trailing `~` is replaced by
// `os.homedir()`
// path: '~/.config/mpd/socket'
// if MPD requires a password, pass
// it within the config as well:
//password: 'password'
}
const client = await mpd.connect(config)
// without config will default to `localhost:6600`
// const client = await mpd.connect()
const status = await client.sendCommand('status').then(mpd.parseObject)
console.log(status)
client.on('close', () => {
console.log('client connection closed')
})
client.on('system', name => {
console.log('on system event: %s', name)
})
client.on('system-player', () => {
console.log('on system player event')
})
await client.disconnect()
```
```ts
// typings included
import mpd, { MPD } from 'mpd2'
type Status = {
volume: number
repeat: boolean
playlist: number
state: 'play' | 'stop' | 'pause'
// ...
}
type ListAllInfo = {
directory: string
last_modified: string
file?: File[]
}
type File = {
file: string
last_modified: string
format: string
time: number
artist: string
title: string
// ...
}
const client: MPD.Client = await mpd.connect()
const statusString = await client.sendCommand('status')
const status = mpd.parseObject<Status>(statusString)
console.log('state:', status.state)
const lsAllParser = mpd.parseListAndAccumulate<ListAllInfo>(['directory', 'file'])
const lsAllString = await client.sendCommand('listallinfo')
const lsAll = lsAllParser(lsAllString)
console.log('first directory: %s, files: %o', lsAll[0].directory, lsAll[0].file)
try {
await client.sendCommands([
'status',
mpd.cmd('foo', 'bar')
])
} catch (e) {
const err: MPD.MPDError = e
switch (err.errno) {
case mpd.MPDError.CODES.UNKNOWN:
console.log('command does not exist')
break;
default:
console.log('some other error', err)
break;
}
}
```
See also the [MPD Protocol Documentation](https://www.musicpd.org/doc/html/protocol.html).
*
`command` can be a `MpdClient.Command` or a string, use *mpd.cmd* helper to construct the Command when using arguments:
```js
await client.sendCommand(mpd.cmd('setvol', [50]))
// args can be overloaded as well, no need to pass them as array:
const searched = await client.sendCommand(
mpd.cmd('search', '(artist contains "Empire")', 'group', 'album'))
```
*
`commandList` will be wrapped between `command_list_begin` and `command_list_end` (see MPD documentation for more info)
*
Disconnects the client.
*
Connects to a MPD server and returns a client.
*
Convert name/args pair into a Command.
*
Getter / setter to enable normalization of keys while parsing. MPD responses contains various keys, upper/lower/kebap cases, this setting normalizes all keys into *snake_case*.
Turned on by default
*
Getter / setter to enable auto parsing of known values based on keys.
Turned on by default
*
`msg`: a string which contains an MPD response.
Returns an object.
*
`msg`: a string which contains an MPD response.
`delimiters`: which keys represent distinct object types within the response
Returns an array, see source for more info
*
`delimiters`: a string or array of delimiters
returns wrapped function `parser(msg)` which calls `parseList(msg, delimiters)`
```js
const songparser = mpd.parseList.by('file')
await client.sendCommand('listallinfo').then(songparser)
```
*
`msg`: a string which contains an MPD response.
Parse the list response, first item key indicates the unique key identifier, any subtiems will be nested within that object. Returns an array of parsed objects. See source for more info.
*
`msg`: a string which contains an MPD response.
`path`: array of nested objects
Parse the list response and nest objects based on *path*. See source for more info.
*
The connection is closed.
*
A system has updated. `systemName` is one of:
* `database` - the song database has been modified after update.
* `update` - a database update has started or finished. If the database was
modified during the update, the database event is also emitted.
* `stored_playlist` - a stored playlist has been modified, renamed, created
or deleted
* `playlist` - the current playlist has been modified
* `player` - the player has been started, stopped or seeked
* `mixer` - the volume has been changed
* `output` - an audio output has been enabled or disabled
* `options` - options like repeat, random, crossfade, replay gain
* `sticker` - the sticker database has been modified.
* `subscription` - a client has subscribed or unsubscribed to a channel
* `message` - a message was received on a channel this client is subscribed
to; this event is only emitted when the queue is empty
*
See above event. Each system name has its own event as well.
*
Protocol version returned by the MPD server after connection is established
*
*MPDError.CODES* contains ACK codes map, as seen here [Ack.hxx](https://github.com/MusicPlayerDaemon/MPD/blob/master/src/protocol/Ack.hxx)
```js
MPDError.CODES = {
NOT_LIST: 1,
ARG: 2,
PASSWORD: 3,
PERMISSION: 4,
UNKNOWN: 5,
NO_EXIST: 50,
PLAYLIST_MAX: 51,
SYSTEM: 52,
PLAYLIST_LOAD: 53,
UPDATE_ALREADY: 54,
PLAYER_SYNC: 55,
EXIST: 56
}
```
All errors thrown by MPD are converted into MPDError isntance:
```js
// MPD ACK line looks like
'ACK [error@command_listNum] {current_command} message_text'
err.code = 'ARG' // one of CODES
err.errno = 2 // for CODES.ARG
err.message = 'whatever mpd returned'
err.cmd_list_num = x // whatever MPD returned as listNum found in MPD ACK line
err.current_command = 'which command this error relates to' // found by MPD ACK line
```