node mpd client api

Api implementation for Music Player Daemon (GIT) protocol.

Wraps the MPD client from mpd2 module with api methods exposed as client.api.x

Usage

npm i / yarn add mpd-api

const mpdapi = require('mpd-api')

// 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 mpdapi.connect(config)

const songs = await client.api.db.search('(artist contains "Empire")')
// [{
//   file: 'mpd/music/path//Sleep Wont Sleep - The Cat Empire (2013).m4a',
//   last_modified: '2019-04-05T14:59:00Z',
//   format: '44100:f:2',
//   time: 284,
//   duration: 284.375,
//   artist: 'The Cat Empire',
//   album: 'Steal the Light',
//   title: "Sleep Won't Sleep",
//   track: 10,
//   date: '2013-05-17',
//   disc: 1,
//   label: 'EMI',
//   albumartist: 'The Cat Empire',
//   musicbrainz_artistid: 'a530492f-8806-4bd7-9c14-80c237eb92fe',
//   musicbrainz_albumid: 'aa62c3b7-2576-4375-9301-ed8824966752',
//   musicbrainz_albumartistid: 'a530492f-8806-4bd7-9c14-80c237eb92fe',
//   musicbrainz_trackid: 'b0261a37-8a91-4581-8eab-4c5069d057ea',
//   musicbrainz_releasetrackid: '56f73f38-c224-4827-a7a2-4552990c5da9'
//  }, {
//   file: ...
//  }, ...]

const status = await client.api.status.get()
// { volume: 63,
// repeat: false,
// random: false,
// single: false,
// consume: false,
// playlist: 312,
// playlistlength: 12,
// mixrampdb: 0,
// state: 'play',
// song: 7,
// songid: 116,
// time: { elapsed: 10562, total: 0 },
// elapsed: 10561.648,
// bitrate: '96',
// audio:
//  { sampleRate: 44100,
//    bits: 24,
//    channels: 2,
//    sample_rate_short: { value: 44.1, unit: 'kHz' } },
// nextsong: 8,
// nextsongid: 117 }

All methods return already parsed results.

Reference to mpd2 module is exposed as well, if needed:

const { mpd } = mpdapi
const { cmd, MPDError } = mpd

try {
  client = await mpdapi.connect()
} catch (e) {
  if (e.errno === MPDError.CODES.PERMISSION) {
    console.log('no permission to connect, probably invalid/missing password')
  }
}

// or disable parsing of values
mpd.autoparseValues(false)

// and do not convert object keys to snake_case
mpd.normalizeKeys(false)

typescript

// typings included

import api, { MPDApi } from 'mpd-api'

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: MPDApi.ClientAPI = await api.connect()

const status = await client.api.status.get<Status>()
console.log('state:', status.state)

const lsAll = await client.api.db.listallinfo<ListAllInfo>()
console.log('first directory: %s, files: %o', lsAll[0].directory, lsAll[0].file)


// reference to mpd2 module:
api.mpd.normalizeKeys(false)

API

Client to client communication MPD documentation

async c2c.list(...args) --> channels ...args

method ignores EXIST, expect undefined in this case

method ignores NO_EXIST, expect undefined in this case

async c2c.sendMessage(...args) --> sendmessage ...args

async c2c.readMessages(...args) --> readmessages ...args

Connection settings MPD documentation

async connection.close(...args) --> close ...args

async connection.kill(...args) --> kill ...args

async connection.ping(...args) --> ping ...args

async connection.getTagTypes(...args) --> tagtypes ...args

method binds arguments which can not be changed

method binds arguments which can not be changed

method binds arguments which can not be changed

method binds arguments which can not be changed

async connection.binarylimit(...args) --> binarylimit ...args

The music database MPD documentation

async db.listall(...args) --> listall ...args

async db.listallinfo(...args) --> listallinfo ...args

method reorderes or augments passed arguments, see dbList

async db.count(...args) --> count ...args

async db.find(...args) --> find ...args

async db.findadd(...args) --> findadd ...args

async db.search(...args) --> search ...args

async db.searchadd(...args) --> searchadd ...args

async db.searchaddpl(...args) --> searchaddpl ...args

async db.lsinfo(...args) --> lsinfo ...args

async db.songinfo(...args) --> lsinfo ...args

async db.listfiles(...args) --> listfiles ...args

async db.readcomments(...args) --> readcomments ...args

async db.rescan(...args) --> rescan ...args

async db.update(...args) --> update ...args

async db.getfingerprint(...args) --> getfingerprint ...args

method ignores NO_EXIST, expect undefined in this case

method ignores NO_EXIST, expect undefined in this case

method ignores NO_EXIST, expect undefined in this case

method ignores NO_EXIST, expect undefined in this case

Mounts and neighbors MPD documentation

async mounts.list(...args) --> listmounts ...args

async mounts.listNeighbors(...args) --> listneighbors ...args

async mounts.mount(...args) --> mount ...args

async mounts.unmount(...args) --> unmount ...args

Audio output devices MPD documentation

async outputs.list(...args) --> outputs ...args

async outputs.enable(...args) --> enableoutput ...args

async outputs.disable(...args) --> disableoutput ...args

async outputs.toggle(...args) --> toggleoutput ...args

async outputs.set(...args) --> outputset ...args

Partition commands MPD documentation

async partition.list(...args) --> listpartitions ...args

method ignores EXIST, expect undefined in this case

async partition.switchTo(...args) --> partition ...args

method ignores NO_EXIST, expect undefined in this case

method ignores NO_EXIST, expect undefined in this case

Playback options and controls MPD documentation

async playback.next(...args) --> next ...args

async playback.prev(...args) --> previous ...args

method binds arguments which can not be changed

method binds arguments which can not be changed

async playback.toggle(...args) --> pause ...args

async playback.play(...args) --> play ...args

async playback.playid(...args) --> playid ...args

async playback.stop(...args) --> stop ...args

async playback.seekcur(...args) --> seekcur ...args

async playback.seek(...args) --> seek ...args

async playback.seekid(...args) --> seekid ...args

async playback.getvol(...args) --> getvol ...args

method reorderes or augments passed arguments, see boolAt

async playback.crossfade(...args) --> crossfade ...args

async playback.mixrampdb(...args) --> mixrampdb ...args

method reorderes or augments passed arguments, see mixrampdelay

method reorderes or augments passed arguments, see boolAt

method reorderes or augments passed arguments, see boolAt

method reorderes or augments passed arguments, see single

async playback.setvol(...args) --> setvol ...args

method reorderes or augments passed arguments, see replaygain

async playback.getReplayGain(...args) --> replay_gain_status ...args

Stored playlists MPD documentation

async playlists.get(...args) --> listplaylists ...args

async playlists.list(...args) --> listplaylist ...args

async playlists.listinfo(...args) --> listplaylistinfo ...args

async playlists.load(...args) --> load ...args

async playlists.add(...args) --> playlistadd ...args

async playlists.clear(...args) --> playlistclear ...args

async playlists.deleteAt(...args) --> playlistdelete ...args

async playlists.move(...args) --> playlistmove ...args

async playlists.rename(...args) --> rename ...args

async playlists.remove(...args) --> rm ...args

async playlists.save(...args) --> save ...args

The Queue MPD documentation

async queue.add(...args) --> add ...args

async queue.addid(...args) --> addid ...args

async queue.clear(...args) --> clear ...args

async queue.info(...args) --> playlistinfo ...args

async queue.id(...args) --> playlistid ...args

async queue.delete(...args) --> delete ...args

async queue.deleteid(...args) --> deleteid ...args

async queue.move(...args) --> move ...args

async queue.moveid(...args) --> moveid ...args

async queue.find(...args) --> playlistfind ...args

async queue.search(...args) --> playlistsearch ...args

async queue.prio(...args) --> prio ...args

async queue.prioid(...args) --> prioid ...args

async queue.shuffle(...args) --> shuffle ...args

async queue.swap(...args) --> swap ...args

async queue.swapid(...args) --> swapid ...args

async queue.addtagid(...args) --> addtagid ...args

async queue.cleartagid(...args) --> cleartagid ...args

async queue.getChanges(...args) --> plchanges ...args

async queue.getChangesPosId(...args) --> plchangesposid ...args

async queue.rangeid(...args) --> rangeid ...args

Reflection MPD documentation

async reflection.config(...args) --> config ...args

async reflection.commands(...args) --> commands ...args

async reflection.notcommands(...args) --> notcommands ...args

async reflection.urlhandlers(...args) --> urlhandlers ...args

async reflection.decoders(...args) --> decoders ...args

Querying MPD’s status MPD documentation

async status.get(...args) --> status ...args

async status.clearerror(...args) --> clearerror ...args

async status.currentsong(...args) --> currentsong ...args

async status.stats(...args) --> stats ...args

Stickers MPD documentation

method binds arguments which can not be changed

method binds arguments which can not be changed

method reorderes or augments passed arguments, see stickerSet

method binds arguments which can not be changed

method ignores NO_EXIST, expect undefined in this case

method binds arguments which can not be changed

method reorderes or augments passed arguments, see stickerDel

method ignores NO_EXIST, expect undefined in this case

method binds arguments which can not be changed

method ignores NO_EXIST, expect undefined in this case

method binds arguments which can not be changed

method reorderes or augments passed arguments, see stickerFind

method binds arguments which can not be changed

method reorderes or augments passed arguments, see stickerSearch