AMPACHE LIBRARY FOR PYTHON3

Upload to PyPI

INFO

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

https://ampache.org/api/

Code examples and scripts are available from github

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

https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/MANUAL.md

This library supports connecting to any Ampache API release (3, 4, 5, 6 and 8)

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 sys
import time

# Open Ampache library
ampache_connection = ampache.API()

# Set your server details
# AMPACHE_VERSION now defaults to 8.1.1, so if your server is on
# API6 (or older) call set_version() with your server's version
ampache_connection.set_version('6.6.1')
ampache_connection.set_url('https://music.com.au')
ampache_connection.set_key('mypassword')
ampache_connection.set_user('myusername')

# Password auth requires a timestamp for encrypting the auth key
ampache_session = ampache_connection.execute('handshake', {'timestamp': int(time.time())})
if not ampache_session:
    # if using an api key you don't need the timestamp to use encrypt_string
    ampache_session = ampache_connection.execute('handshake')

# Fail if you didn't connect
if not ampache_session:
    sys.exit(ampache_connection.AMPACHE_VERSION + ' ERROR Failed to connect to ' + ampache_connection.AMPACHE_URL)

# now you can call methods without having to keep putting in the url and userkey
artists = ampache_connection.execute('artists', {'limit': 10})

# You can parse a response to get a list of ID's for that response
artist_ids = ampache_connection.get_id_list(artists, 'artist')
if artist_ids:
    print("We found some artists")
    for artist in artist_ids:
        print('ID:', artist)

# ping has always allowed empty calls so you have to ping with a session key
ampache_connection.execute('ping', {'ampache_api': ampache_session})

NEWS

• 8.1.1 adds support for Ampache API8: folders, album disks, playlist folders, collections, and a type-aware playlist_remove. See CHANGELOG.md for the full list.

• 8.1.1 breaking changes affecting all callers regardless of server API version:

  • AMPACHE_VERSION now defaults to 8.1.1 instead of 6.9.0 — call set_version() explicitly if you’re on an older API.

  • HTTP error responses are returned instead of False (call set_return_http_errors(False) to restore the old behavior).

  • users(), stream(), download() and get_indexes() changed parameter order — positional callers must update their call sites, keyword callers are unaffected.

• get_indexes, playlist_add_song, playlist_remove_song and user_update are deprecated in favor of index, playlist_add, playlist_remove and user_edit.

• Examples are being updated to support the latest execute method which can simplify your code

• 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”

INSTALL

You can now install from pip directly:

pip3 install -U ampache

EXAMPLES

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.

https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/examples/ampyche.py

ampyche.py 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, list, 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 6.x.x+ to scrobble a track to your server

import ampache
import sys
import time

# Open Ampache library
ampache_connection = ampache.API()

# load up previous config
if not ampache_connection.get_config():
    # Set your details manually if we can't get anything
    # use your server's own API version here (defaults to 8.1.1)
    ampache_connection.set_version('6.6.1')
    ampache_connection.set_url('https://music.server')
    ampache_connection.set_key('mysuperapikey')
    ampache_connection.set_user('myusername')

# Get a session key using the handshake
#
# * ampache_url = (string) Full Ampache URL e.g. 'https://music.com.au'
# * ampache_api = (string) encrypted apikey OR password if using password auth
# * user        = (string) username //optional
# * timestamp   = (integer) UNIXTIME() //optional
# * version     = (string) API Version //optional
ampache_session = ampache_connection.execute('handshake')

# Fail if you didn't connect
if not ampache_session:
    sys.exit(ampache_connection.AMPACHE_VERSION + ' ERROR Failed to connect to ' + ampache_connection.AMPACHE_URL)

# save your successful connection in your local config
ampache_connection.save_config()

# Scrobble a music track to your ampache server
#
# * title       = (string) song title
# * artist_name = (string) artist name
# * album_name  = (string) album name
# * mbtitle     = (string) song mbid //optional
# * mbartist    = (string) artist mbid //optional
# * mbalbum     = (string) album mbid //optional
# * stime       = (integer) UNIXTIME() //optional
# * client      = (string) //optional
ampache_connection.execute('scrobble', {'title': 'Beneath The Cold Clay',
                                        'artist_name': 'Crust',
                                        'album_name': '...and a Dirge Becomes an Anthem',
                                        'stime': int(time.time())})

POWERED BY

PhpStorm logo

JetBrains have supported the project for many years now and their tools really do power Ampache development.

LINKS

https://github.com/ampache/python3-ampache/

https://pypi.org/project/ampache/