Amarok REST API

January 1, 2009

I’ve been working on the guts of a REST API for Amarok though PHP and DCOP. Thought I’d share my JSON format because I’m proud of it. Also because I’m bound to lose the format file sooner or later.

There are two basic things you can do with Amarok: take an action and ask for information. So that’s how I broke it down, action and info blocks in every request.

Rather than codify it in any formal way I’m just going to show examples.

Action – Toggle play/pause condition
Request

{
  'action': {
    '0': {
      'name':'playPause',
      'params': false
    }
  }
}

Response

{
  'action': {
    '0': {
      'name':'playPause',
      'error':false
    }
  }
}

Action – Play and set the equalizer
Request

{
  'action': {
    '0': {
      'name':'play',
      'params': false
    },
    '1': {
      'name':'setEqualizer',
      'params': {
        '0':'20',
        '1':'30',
        '2':'40',
        '3':'10',
        '4':'20',
        '5':'30',
        '6':'40',
        '7':'10',
        '8':'20',
        '9':'30',
        '10':'40',
        '11':'10',
      }
    }
  }
}

Response

{
  'action': {
    '0': {
      'name':'playPause',
      'error':false
    },
    '1': {
      'name':'setEqualizer',
      'error':false
    }
  }
}

Info – Get playing track album name
Request

{
  'info': {
    '0': {
      'name':'album',
      'params': false
    }
  }
}

Response

{
  'info': {
    '0': {
      'name':'album',
      'value':'Doppleganger'
    }
  }
}

Info – Get playing track album name, artist and title.
Request

{
  'info': {
    '0': {
      'name':'album',
      'params':false
    },
    '1': {
      'name':'artist',
      'params':false
    },
    '3': {
      'name':'title',
      'params':false
    }
  }
}

Response

{
  'info': {
    '0': {
      'name':'album',
      'value':'Doppleganger'
    },
    '1': {
      'name':'artist',
      'value':'The Fall of Troy'
    },
    '3': {
      'name':'title',
      'value':'F.C.P.R.E.M.I.X'
    }
  }
}

Both – Go to next track, get that track artist.
Note: I have decided that when both action and info are present they will alternate execution starting on action (i.e. action 0 then info 0 then action 1 and so on.) Thus we will probably want to create a NOP at some point.
Request

{
  'action': {
    '0': {
      'name':'next',
      'params': false
    }
  },
  'info': {
    '0': {
      'name':'artist',
      'params':false
    }
  }
}

Response

{
  'action': {
    '0': {
      'name':'playPause',
      'error':false
    }
  },
  'info': {
    '0': {
      'name':'artist',
      'value':'Far-Less'
    }
  }
}

Leave A Comment

Your email will not be published.