Python library for Ampache XML & JSON API
Project description
AMPACHE LIBRARY FOR PYTHON3
INFO
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.
https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/MANUAL.md
This library supports connecting to any Ampache API release (3, 4, 5 and 6)
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_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
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
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
JetBrains have supported the project for many years now and their tools really do power Ampache development.
LINKS
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file ampache-6.8.0.tar.gz
.
File metadata
- Download URL: ampache-6.8.0.tar.gz
- Upload date:
- Size: 37.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
9ce8c51c4372a77ea7d13a5beb89b3284f1b798fc8dcbcfa64a66a5122a51253
|
|
MD5 |
994fdbce67a6588bf0e245c78dea09e9
|
|
BLAKE2b-256 |
09a4dd873308b3326bf776cbde6d30051078fac11da6375c6380439533cf6692
|
File details
Details for the file ampache-6.8.0-py3-none-any.whl
.
File metadata
- Download URL: ampache-6.8.0-py3-none-any.whl
- Upload date:
- Size: 37.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
e3019e507aaca2cb386a4dd6dcea25865bfa654fdcc8bd9d3060a94cf006cb4a
|
|
MD5 |
72bf02b075de66514f200642ebb7c1c8
|
|
BLAKE2b-256 |
754cd6b36b10d4e94b2c12d07ef2af5d82f07b0cd44cafe299ff21bc67e19115
|