Skip to main content

Python library for Ampache XML & JSON API

Project description


Upload to PyPI


A python3 library for interaction with your Ampache server using the XML & JSON API

Code examples and scripts are available from github

The class documentation has been extracted out into a markdown file for easier reading.

There has been a pretty significant change in the library between Ampache 4 and Ampache 5.

For anyone wanting to stay on v4 the branch has been separated from the master branch.

Once you connect with your passphrase or api key, the url and auth token are stored allowing you to call methods without them.

import ampache
import time

# connect to the server
ampacheConnection = ampache.API()

# if using password auth use encrypt_password
mytime = int(time.time())
passphrase = ampacheConnection.encrypt_password('mypassword', mytime)
auth = ampacheConnection.handshake('', passphrase, 'my username', mytime)

# if using an API key auth keep using encrypt_string
passphrase = ampacheConnection.encrypt_string('my apikey', 'my username')
auth = ampacheConnection.handshake('', passphrase)

# now you can call methods without having to keep putting in the url and userkey

# ping has always allowed empty calls so you have to ping with a url and session still'', auth)


  • Password handshake auth is available now.

  • This library now supports every Ampache API release (3, 4, 5 and 6)

  • You can save and restore from a json config file using new methods

    • set_config_path: Set a folder to your config path

    • get_config: Load the config and set Ampache globals

    • save_config: Save the config file with the current globals

      • AMPACHE_URL = The URL of your Ampache server

      • AMPACHE_USER = config[“ampache_user”]

      • AMPACHE_KEY = Your encrypted apikey OR password if using password auth

      • AMPACHE_SESSION = Current session auth from the handshake. Use to reconnect to an existing session

      • AMPACHE_API = API output format “json” || “xml”


You can now install from pip directly:

pip3 install -U ampache


There is a fairly simple cli example for windows/linux to perform a few functions. It’s a good example for testing and might make things a bit easier to follow. help:

Possible Actions:

    /u:%CUSTOM_USER%    (Custom username for the current action)
    /k:%CUSTOM_APIKEY%  (Custom apikey for the current action)
    /a:%ACTION%         (ping, playlists, localplay, download, configure, logout, showconfig)
    /l:%LIMIT%          (integer)
    /o:%OBJECT_ID%      (string)
    /t:%OBJECT_TYPE%    (song, playlist)
    /p:%PATH%           (folder for downloads)
    /f:%FORMAT%         (raw, mp3, ogg, flac)
    /usb                (split files into numeric 0-9 folders for car USBs)
    /c:%COMMAND%        (localplay command)
    (next, prev, stop, play, pause, add, volume_up,
        volume_down, volume_mute, delete_all, skip, status)

Here is a short code sample for python using version 5.x.x+ to scrobble a track to your server

import time
import ampache

# user variables
ampache_url = 'https://music.server'
my_api_key = 'mysuperapikey'
user = 'myusername'

# processed details
ampacheConnection = ampache.API()
encrypted_key = ampacheConnection.encrypt_string(my_api_key, user)
ampache_session = ampacheConnection.handshake(ampache_url, encrypted_key)

if ampache_session:
    # Scrobble a music track to your ampache server
            args=('Beneath The Cold Clay', 'Crust', '...and a Dirge Becomes an Anthem',
                  '', '', '', int(time.time()))).start()

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ampache-6.6.0.tar.gz (32.5 kB view hashes)

Uploaded Source

Built Distribution

ampache-6.6.0-py3-none-any.whl (32.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page