From 5c875c50de462b5c92af84efbe1db6f848bfa4bb Mon Sep 17 00:00:00 2001 From: Callum Brown Date: Mon, 21 Sep 2020 20:24:41 +0100 Subject: [PATCH 01/14] AURA: Add aura plugin and docs --- beetsplug/aura.py | 847 +++++++++++++++++++++++++++++++++++++++++ docs/plugins/aura.rst | 195 ++++++++++ docs/plugins/index.rst | 3 + 3 files changed, 1045 insertions(+) create mode 100644 beetsplug/aura.py create mode 100644 docs/plugins/aura.rst diff --git a/beetsplug/aura.py b/beetsplug/aura.py new file mode 100644 index 0000000000..4269a4df8b --- /dev/null +++ b/beetsplug/aura.py @@ -0,0 +1,847 @@ +# -*- coding: utf-8 -*- + +# This file is part of beets. +# Copyright 2020, Callum Brown. +# +# Permission is hereby granted, free of charge, to any person obtaining +# a copy of this software and associated documentation files (the +# "Software"), to deal in the Software without restriction, including +# without limitation the rights to use, copy, modify, merge, publish, +# distribute, sublicense, and/or sell copies of the Software, and to +# permit persons to whom the Software is furnished to do so, subject to +# the following conditions: +# +# The above copyright notice and this permission notice shall be +# included in all copies or substantial portions of the Software. + +"""An AURA server using Flask. +""" + +from __future__ import division, absolute_import, print_function + +from mimetypes import guess_type +import re +from os.path import isfile, getsize + +from beets.plugins import BeetsPlugin +from beets.ui import Subcommand, _open_library +from beets import config +from beets.util import displayable_path +from beets.library import Item, Album +from beets.dbcore.query import ( + MatchQuery, + NotQuery, + RegexpQuery, + AndQuery, + FixedFieldSort, + SlowFieldSort, + MultipleSort, +) + +from flask import ( + Blueprint, + Flask, + current_app, + send_file, + make_response, + request, +) + + +# Constants + +# AURA server information +# TODO: Add version information +SERVER_INFO = { + "aura-version": "0", + "server": "beets-aura", + "server-version": "0", + "auth-required": False, + "features": ["albums", "artists", "images"], +} + +# Maps AURA Track attribute to beets Item attribute +TRACK_ATTR_MAP = { + # Required + "title": "title", + "artist": "artist", + # Optional + "album": "album", + "track": "track", # Track number on album + "tracktotal": "tracktotal", + "disc": "disc", + "disctotal": "disctotal", + "year": "year", + "month": "month", + "day": "day", + "bpm": "bpm", + "genre": "genre", + "recording-mbid": "mb_trackid", # beets trackid is MB recording + "track-mbid": "mb_releasetrackid", + "composer": "composer", + "albumartist": "albumartist", + "comments": "comments", + # Optional for Audio Metadata + # TODO: Support the mimetype attribute, format != mime type + # "mimetype": track.format, + "duration": "length", + "framerate": "samplerate", + # I don't think beets has a framecount field + # "framecount": ???, + "channels": "channels", + "bitrate": "bitrate", + "bitdepth": "bitdepth", + "size": "filesize", +} + +# Maps AURA Album attribute to beets Album attribute +ALBUM_ATTR_MAP = { + # Required + "title": "album", + "artist": "albumartist", + # Optional + "tracktotal": "albumtotal", + "disctotal": "disctotal", + "year": "year", + "month": "month", + "day": "day", + "genre": "genre", + "release-mbid": "mb_albumid", + "release-group-mbid": "mb_releasegroupid", +} + +# Maps AURA Artist attribute to beets Item field +# Artists are not first-class in beets, so information is extracted from +# beets Items. +ARTIST_ATTR_MAP = { + # Required + "name": "artist", + # Optional + "artist_mbid": "mb_artistid", +} + + +class AURADocument: + """Base class for building AURA documents.""" + + @staticmethod + def error(status, title, detail): + """Make a response for an error following the JSON:API spec.""" + document = { + "errors": [{"status": status, "title": title, "detail": detail}] + } + return make_response(document, status) + + def translate_attribute(self, aura_attr): + """Translate AURA attribute name to beets attribute name.""" + try: + return self.attribute_map[aura_attr] + except KeyError: + # Assume native beets attribute + return aura_attr + + def translate_filters(self): + """Translate filters from request arguments to a beets Query.""" + # The format of each filter key in the request parameter is: + # filter[]. This regex extracts . + pattern = re.compile(r"filter\[(?P\w+)\]") + queries = [] + for key, value in request.args.items(): + match = pattern.match(key) + if match is not None: + # Extract attribute name from key + aura_attr = match.group("attribute") + # Get the beets version of the attribute name + beets_attr = self.translate_attribute(aura_attr) + converter = self.get_attribute_converter(beets_attr) + value = converter(value) + # Add exact match query to list + # Use a slow query so it works with all fields + queries.append(MatchQuery(beets_attr, value, fast=False)) + # NOTE: AURA doesn't officially support multiple queries + return AndQuery(queries) + + def translate_sorts(self, sort_arg): + """Translate an AURA sort parameter into a beets Sort.""" + # Change HTTP query parameter to a list + aura_sorts = sort_arg.strip(",").split(",") + sorts = [] + for aura_attr in aura_sorts: + if aura_attr[0] == "-": + ascending = False + # Remove leading "-" + aura_attr = aura_attr[1:] + else: + # JSON:API default + ascending = True + # Get the beets version of the attribute name + beets_attr = self.translate_attribute(aura_attr) + # Use slow sort so it works with all fields (inc. computed) + sorts.append(SlowFieldSort(beets_attr, ascending=ascending)) + return MultipleSort(sorts) + + def paginate(self, collection): + """Get a page of the collection and the URL to the next page.""" + # Pages start from zero + page = request.args.get("page", 0, int) + # Use page limit defined in config by default. + default_limit = config["aura"]["page_limit"].get(int) + limit = request.args.get("limit", default_limit, int) + # start = offset of first item to return + start = page * limit + # end = offset of last item + 1 + end = start + limit + if end > len(collection): + end = len(collection) + next_url = None + else: + # Not the last page so work out links.next url + if len(request.args) == 0: + # No existing arguments, so current page is 0 + next_url = request.url + "?page=1" + elif request.args.get("page", None) is None: + # No existing page argument, so add one to the end + next_url = request.url + "&page=1" + else: + # Increment page token by 1 + next_url = request.url.replace( + "page={}".format(page), "page={}".format(page + 1) + ) + # Get only the items in the page range + data = [self.resource_object(collection[i]) for i in range(start, end)] + return data, next_url + + def get_included(self, data, include_str): + """Build a list of resource objects for inclusion. + + :param data: Array of dicts in the form of resource objects + :param include_str: Comma separated list of resources to include + """ + # Change HTTP query parameter to a list + to_include = include_str.strip(",").split(",") + # Build a list of unique type and id combinations + # For each resource object in the primary data, iterate over it's + # relationships. If a relationship matches one of the types + # requested for inclusion (e.g. "albums") then add each type-id pair + # under the "data" key to unique_identifiers, checking first that + # it has not already been added. This ensures that no resources are + # included more than once. + unique_identifiers = [] + for res_obj in data: + for rel_name, rel_obj in res_obj["relationships"].items(): + if rel_name in to_include: + # NOTE: Assumes relationship is to-many + for identifier in rel_obj["data"]: + if identifier not in unique_identifiers: + unique_identifiers.append(identifier) + # TODO: I think this could be improved + included = [] + for identifier in unique_identifiers: + res_type = identifier["type"] + if res_type == "track": + track_id = int(identifier["id"]) + track = current_app.config["lib"].get_item(track_id) + included.append(TrackDocument.resource_object(track)) + elif res_type == "album": + album_id = int(identifier["id"]) + album = current_app.config["lib"].get_album(album_id) + included.append(AlbumDocument.resource_object(album)) + elif res_type == "artist": + artist_id = identifier["id"] + included.append(ArtistDocument.resource_object(artist_id)) + elif res_type == "image": + image_id = identifier["id"] + included.append(ImageDocument.resource_object(image_id)) + else: + raise ValueError("Invalid resource type: {}".format(res_type)) + return included + + def all_resources(self): + """Build document for /tracks, /albums or /artists.""" + query = self.translate_filters() + sort_arg = request.args.get("sort", None) + if sort_arg is not None: + sort = self.translate_sorts(sort_arg) + # For each sort field add a query which ensures all results + # have a non-empty, non-zero value for that field. + for s in sort.sorts: + query.subqueries.append( + NotQuery( + # Match empty fields (^$) or zero fields, (^0$) + RegexpQuery(s.field, "(^$|^0$)", fast=False) + ) + ) + else: + sort = None + # Get information from the library + collection = self.get_collection(query=query, sort=sort) + # Convert info to AURA form and paginate it + data, next_url = self.paginate(collection) + document = {"data": data} + # If there are more pages then provide a way to access them + if next_url is not None: + document["links"] = {"next": next_url} + # Include related resources for each element in "data" + include_str = request.args.get("include", None) + if include_str is not None: + document["included"] = self.get_included(data, include_str) + return document + + def single_resource_document(self, resource_object): + """Build document for a specific requested resource.""" + document = {"data": resource_object} + include_str = request.args.get("include", None) + if include_str is not None: + # [document["data"]] is because arg needs to be list + document["included"] = self.get_included( + [document["data"]], include_str + ) + return document + + +class TrackDocument(AURADocument): + """Class for building documents for /tracks endpoints.""" + + attribute_map = TRACK_ATTR_MAP + + def get_collection(self, query=None, sort=None): + """Get Item objects from the library.""" + return current_app.config["lib"].items(query, sort) + + def get_attribute_converter(self, beets_attr): + """Work out what data type an attribute should be for beets.""" + # filesize is a special field (read from disk not db?) + if beets_attr == "filesize": + converter = int + else: + try: + # Look for field in list of Item fields + # and get python type of database type. + # See beets.library.Item and beets.dbcore.types + converter = Item._fields[beets_attr].model_type + except KeyError: + # Fall back to string (NOTE: probably not good) + converter = str + return converter + + @staticmethod + def resource_object(track): + """Construct a JSON:API resource object from a beets Item.""" + attributes = {} + # Use aura => beets attribute map, e.g. size => filesize + for aura_attr, beets_attr in TRACK_ATTR_MAP.items(): + a = getattr(track, beets_attr) + # Only set attribute if it's not None, 0, "", etc. + # NOTE: This could result in required attributes not being set + if a: + attributes[aura_attr] = a + + # JSON:API one-to-many relationship to parent album + relationships = { + "artists": {"data": [{"type": "artist", "id": track.artist}]} + } + # Only add album relationship if not singleton + if not track.singleton: + relationships["albums"] = { + "data": [{"type": "album", "id": str(track.album_id)}] + } + + return { + "type": "track", + "id": str(track.id), + "attributes": attributes, + "relationships": relationships, + } + + def single_resource(self, track_id): + """Get track from the library and build a document.""" + track = current_app.config["lib"].get_item(track_id) + if track is None: + return self.error( + "404 Not Found", + "No track with the requested id.", + ("There is no track with an id of {} in the library.").format( + track_id + ), + ) + return self.single_resource_document(self.resource_object(track)) + + +class AlbumDocument(AURADocument): + """Class for building documents for /albums endpoints.""" + + attribute_map = ALBUM_ATTR_MAP + + def get_collection(self, query=None, sort=None): + """Get Album objects from the library.""" + return current_app.config["lib"].albums(query, sort) + + def get_attribute_converter(self, beets_attr): + """Work out what data type an attribute should be for beets.""" + # filesize is a special field (read from disk not db?) + try: + # Look for field in list of Album fields + # and get python type of database type. + # See beets.library.Album and beets.dbcore.types + converter = Album._fields[beets_attr].model_type + except KeyError: + # Fall back to string (NOTE: probably not good) + converter = str + return converter + + @staticmethod + def resource_object(album): + """Construct a JSON:API resource object from a beets Album.""" + attributes = {} + # Use aura => beets attribute name map + for aura_attr, beets_attr in ALBUM_ATTR_MAP.items(): + a = getattr(album, beets_attr) + # Only set attribute if it's not None, 0, "", etc. + # NOTE: This could mean required attributes are not set + if a: + attributes[aura_attr] = a + + # Get beets Item objects for all tracks in the album sorted by + # track number. Sorting is not required but it's nice. + query = MatchQuery("album_id", album.id) + sort = FixedFieldSort("track", ascending=True) + tracks = current_app.config["lib"].items(query, sort) + # JSON:API one-to-many relationship to tracks on the album + relationships = { + "tracks": { + "data": [{"type": "track", "id": str(t.id)} for t in tracks] + } + } + # Add images relationship if album has associated images + if album.artpath is not None: + path = displayable_path(album.artpath) + filename = path.split("/")[-1] + image_id = "album-{}-{}".format(album.id, filename) + relationships["images"] = { + "data": [{"type": "image", "id": image_id}] + } + # Add artist relationship if artist name is same on tracks + # Tracks are used to define artists so don't albumartist + # Check for all tracks in case some have featured artists + if album.albumartist in [t.artist for t in tracks]: + relationships["artists"] = { + "data": [{"type": "artist", "id": album.albumartist}] + } + + return { + "type": "album", + "id": str(album.id), + "attributes": attributes, + "relationships": relationships, + } + + def single_resource(self, album_id): + """Get album from the library and build a document.""" + album = current_app.config["lib"].get_album(album_id) + if album is None: + return self.error( + "404 Not Found", + "No album with the requested id.", + ("There is no album with an id of {} in the library.").format( + album_id + ), + ) + return self.single_resource_document(self.resource_object(album)) + + +class ArtistDocument(AURADocument): + """Class for building documents for /artists endpoints.""" + + attribute_map = ARTIST_ATTR_MAP + + def get_collection(self, query=None, sort=None): + """Get a list of artist names from the library.""" + # Gets only tracks with matching artist information + tracks = current_app.config["lib"].items(query, sort) + collection = [] + for track in tracks: + # Do not add duplicates + if track.artist not in collection: + collection.append(track.artist) + return collection + + def get_attribute_converter(self, beets_attr): + """Work out what data type an attribute should be for beets.""" + try: + # Look for field in list of Item fields + # and get python type of database type. + # See beets.library.Item and beets.dbcore.types + converter = Item._fields[beets_attr].model_type + except KeyError: + # Fall back to string (NOTE: probably not good) + converter = str + return converter + + @staticmethod + def resource_object(artist_id): + """Construct a JSON:API resource object for the given artist.""" + # Get tracks where artist field exactly matches artist_id + query = MatchQuery("artist", artist_id) + tracks = current_app.config["lib"].items(query) + if len(tracks) == 0: + return None + + # Get artist information from the first track + # NOTE: It could be that the first track doesn't have a + # MusicBrainz id but later tracks do, which isn't ideal. + attributes = {} + # Use aura => beets attribute map, e.g. artist => name + for aura_attr, beets_attr in ARTIST_ATTR_MAP.items(): + a = getattr(tracks[0], beets_attr) + # Only set attribute if it's not None, 0, "", etc. + # NOTE: This could mean required attributes are not set + if a: + attributes[aura_attr] = a + + relationships = { + "tracks": { + "data": [{"type": "track", "id": str(t.id)} for t in tracks] + } + } + album_query = MatchQuery("albumartist", artist_id) + albums = current_app.config["lib"].albums(query=album_query) + if len(albums) != 0: + relationships["albums"] = { + "data": [{"type": "album", "id": str(a.id)} for a in albums] + } + + return { + "type": "artist", + "id": artist_id, + "attributes": attributes, + "relationships": relationships, + } + + def single_resource(self, artist_id): + """Get info for the requested artist and build a document.""" + artist_resource = self.resource_object(artist_id) + if artist_resource is None: + return self.error( + "404 Not Found", + "No artist with the requested id.", + ("There is no artist with an id of {} in the library.").format( + artist_id + ), + ) + return self.single_resource_document(artist_resource) + + +class ImageDocument(AURADocument): + """Class for building documents for /images/(id) endpoints.""" + + @staticmethod + def get_image_path(image_id): + """Works out the full path to the image with the given id. + + Returns None if there is no such image. + image_id is in the form -- + """ + # Split image_id into its constituent parts + id_split = image_id.split("-") + if len(id_split) < 3: + # image_id is not in the required format + return None + parent_type = id_split[0] + parent_id = id_split[1] + img_filename = "-".join(id_split[2:]) + + # Get the path to the directory parent's images are in + if parent_type == "album": + album = current_app.config["lib"].get_album(int(parent_id)) + if album is None or album.artpath is None: + return None + # Cut the filename off of artpath + # This is in preparation for supporting images in the same + # directory that are not tracked by beets. + artpath = displayable_path(album.artpath) + dir_path = "/".join(artpath.split("/")[:-1]) + else: + # Images for other resource types are not supported + return None + + img_path = dir_path + "/" + img_filename + # Check the image actually exists + if isfile(img_path): + return img_path + else: + return None + + @staticmethod + def resource_object(image_id): + """Construct a JSON:API resource object for the given image.""" + # Could be called as a static method, so can't use + # self.get_image_path() + image_path = ImageDocument.get_image_path(image_id) + if image_path is None: + return None + + attributes = { + "role": "cover", + "mimetype": guess_type(image_path)[0], + "size": getsize(image_path), + } + try: + from PIL import Image + except ImportError: + pass + else: + im = Image.open(image_path) + attributes["width"] = im.width + attributes["height"] = im.height + + relationships = {} + # Split id into [parent_type, parent_id, filename] + id_split = image_id.split("-") + relationships[id_split[0] + "s"] = { + "data": [{"type": id_split[0], "id": id_split[1]}] + } + + return { + "id": image_id, + "type": "image", + # Remove attributes that are None, 0, "", etc. + "attributes": {k: v for k, v in attributes.items() if v}, + "relationships": relationships, + } + + def single_resource(self, image_id): + """Get info for the requested image and build a document.""" + image_resource = self.resource_object(image_id) + if image_resource is None: + return self.error( + "404 Not Found", + "No image with the requested id.", + ("There is no image with an id of {} in the library.").format( + image_id + ), + ) + return self.single_resource_document(image_resource) + + +# Initialise flask blueprint +aura_bp = Blueprint("aura_bp", __name__) + + +@aura_bp.route("/server") +def server_info(): + """Respond with info about the server.""" + return {"data": {"type": "server", "id": "0", "attributes": SERVER_INFO}} + + +# Track endpoints + + +@aura_bp.route("/tracks") +def all_tracks(): + """Respond with a list of all tracks and related information.""" + doc = TrackDocument() + return doc.all_resources() + + +@aura_bp.route("/tracks/") +def single_track(track_id): + """Respond with info about the specified track.""" + doc = TrackDocument() + return doc.single_resource(track_id) + + +@aura_bp.route("/tracks//audio") +def audio_file(track_id): + """Supply an audio file for the specified track.""" + track = current_app.config["lib"].get_item(track_id) + if track is None: + return AURADocument.error( + "404 Not Found", + "No track with the requested id.", + ("There is no track with an id of {} in the library.").format( + track_id + ), + ) + + path = displayable_path(track.destination()) + if not isfile(path): + return AURADocument.error( + "404 Not Found", + "No audio file for the requested track.", + ( + "There is no audio file for track {} at the expected location" + ).format(track_id), + ) + + file_mimetype = guess_type(path)[0] + if file_mimetype is None: + return AURADocument.error( + "500 Internal Server Error", + "Requested audio file has an unknown mimetype.", + ( + "The audio file for track {} has an unknown mimetype. " + "It's file extension is {}." + ).format(track_id, path.split(".")[-1]), + ) + + # Check that the Accept header contains the file's mimetype + # Takes into account */* and audio/* + # Adding support for the bitrate parameter would require some effort so I + # left it out. This means the client could be sent an error even if the + # audio doesn't need transcoding. + if request.accept_mimetypes.best_match([file_mimetype]) is None: + return AURADocument.error( + "406 Not Acceptable", + "Unsupported MIME type or bitrate parameter in Accept header.", + ( + "The audio file for track {} is only available as {} and " + "bitrate parameters are not supported." + ).format(track_id, file_mimetype), + ) + + return send_file( + path, + mimetype=file_mimetype, + # Handles filename in Content-Disposition header + as_attachment=True, + # Tries to upgrade the stream to support range requests + conditional=True, + ) + + +# Album endpoints + + +@aura_bp.route("/albums") +def all_albums(): + """Respond with a list of all albums and related information.""" + doc = AlbumDocument() + return doc.all_resources() + + +@aura_bp.route("/albums/") +def single_album(album_id): + """Respond with info about the specified album.""" + doc = AlbumDocument() + return doc.single_resource(album_id) + + +# Artist endpoints +# Artist ids are their names + + +@aura_bp.route("/artists") +def all_artists(): + """Respond with a list of all artists and related information.""" + doc = ArtistDocument() + return doc.all_resources() + + +# Using the path converter allows slashes in artist_id +@aura_bp.route("/artists/") +def single_artist(artist_id): + """Respond with info about the specified artist.""" + doc = ArtistDocument() + return doc.single_resource(artist_id) + + +# Image endpoints +# Image ids are in the form -- +# For example: album-13-cover.jpg + + +@aura_bp.route("/images/") +def single_image(image_id): + """Respond with info about the specified image.""" + doc = ImageDocument() + return doc.single_resource(image_id) + + +@aura_bp.route("/images//file") +def image_file(image_id): + """Supply an image file for the specified image.""" + img_path = ImageDocument.get_image_path(image_id) + if img_path is None: + return AURADocument.error( + "404 Not Found", + "No image with the requested id.", + ("There is no image with an id of {} in the library").format( + image_id + ), + ) + return send_file(img_path) + + +# WSGI app + + +def create_app(): + """An application factory for use by a WSGI server.""" + app = Flask(__name__) + # Register AURA blueprint view functions under a URL prefix + app.register_blueprint(aura_bp, url_prefix="/aura") + # AURA specifies mimetype MUST be this + app.config["JSONIFY_MIMETYPE"] = "application/vnd.api+json" + # Disable auto-sorting of JSON keys + app.config["JSON_SORT_KEYS"] = False + # Provide a way to access the beets library + # The normal method of using the Library and config provided in the + # command function is not used because create_app() could be called + # by an external WSGI server. + # NOTE: this uses a 'private' function from beets.ui.__init__ + app.config["lib"] = _open_library(config) + + # Enable CORS if required + cors = config["aura"]["cors"].get(list) + if cors: + from flask_cors import CORS + + # "Accept" is the only header clients use + app.config["CORS_ALLOW_HEADERS"] = "Accept" + app.config["CORS_RESOURCES"] = {r"/aura/*": {"origins": cors}} + app.config["CORS_SUPPORTS_CREDENTIALS"] = config["aura"][ + "cors_supports_credentials" + ].get(bool) + CORS(app) + + return app + + +# Beets Plugin Hook + + +class AURAPlugin(BeetsPlugin): + def __init__(self): + super(AURAPlugin, self).__init__() + self.config.add( + { + "host": u"127.0.0.1", + "port": 8337, + "cors": [], + "cors_supports_credentials": False, + "page_limit": 500, + } + ) + + def commands(self): + def run_aura(lib, opts, args): + """Run the application using Flask's built in-server.""" + app = create_app() + # Start the built-in server (not intended for production) + app.run( + host=self.config["host"].get(str), + port=self.config["port"].get(int), + debug=opts.debug, + threaded=True, + ) + + run_aura_cmd = Subcommand("aura", help=u"run an AURA server") + run_aura_cmd.parser.add_option( + u"-d", + u"--debug", + action="store_true", + default=False, + help=u"use Flask debug mode", + ) + run_aura_cmd.func = run_aura + return [run_aura_cmd] diff --git a/docs/plugins/aura.rst b/docs/plugins/aura.rst new file mode 100644 index 0000000000..2891d25e18 --- /dev/null +++ b/docs/plugins/aura.rst @@ -0,0 +1,195 @@ +AURA Plugin +=========== + +This plugin is a server implementation of the `AURA`_ specification using the +`Flask`_ framework. AURA is still a work in progress and doesn't yet have a +stable version, but this server should be kept up to date. You are advised to +read the :ref:`aura-issues` section. + +.. _AURA: https://auraspec.readthedocs.io +.. _Flask: https://palletsprojects.com/p/flask/ + +Install +------- + +The ``aura`` plugin depends on `Flask`_, which can be installed using +``python -m pip install flask``. Then you can enable the ``aura`` plugin in +your configuration (see :ref:`using-plugins`). + +It is likely that you will need to enable :ref:`aura-cors`, which introduces +an additional dependency: `flask-cors`_. This can be installed with +``python -m pip install flask-cors``. + +If `Pillow`_ is installed (``python -m pip install Pillow``) then the optional +``width`` and ``height`` attributes are included in image resource objects. + +.. _flask-cors: https://flask-cors.readthedocs.io +.. _Pillow: https://pillow.readthedocs.io + + +Usage +----- + +Use ``beet aura`` to start the AURA server. +By default Flask's built-in server is used, which will give a warning about +using it in a production environment. It is safe to ignore this warning if the +server will have only a few users. + +Alternatively, you can use ``beet aura -d`` to start the server in +`development mode`_, which will reload the server every time the AURA plugin +file is changed. + +You can specify the hostname and port number used by the server in your +:doc:`configuration file `. For more detail see the +:ref:`configuration` section below. + +If you would prefer to use a different WSGI server, such as gunicorn or uWSGI, +then see :ref:`aura-external-server`. + +AURA is designed to separate the client and server functionality. This plugin +provides the server but not the client, so unless you like looking at JSON you +will need a separate client. Unfortunately there are no AURA clients yet +(discounting the broken and outdated reference implementation). + +By default the API is served under http://127.0.0.1:8337/aura/. For example +information about the track with an id of 3 can be obtained at +http://127.0.0.1:8337/aura/tracks/3. + +**Note the absence of a trailing slash**: +http://127.0.0.1:8337/aura/tracks/3/ returns a ``404 Not Found`` error. + +.. _development mode: https://flask.palletsprojects.com/en/1.1.x/server + + +.. _configuration: + +Configuration +------------- + +To configure the plugin, make an ``aura:`` section in your +configuration file. The available options are: + +- **host**: The server hostname. Set this to 0.0.0.0 to bind to all interfaces. + Default: ``127.0.0.1``. +- **port**: The server port. + Default: ``8337``. +- **cors**: A YAML list of origins to allow CORS requests from (see + :ref:`aura-cors`, below). + Default: disabled. +- **cors_supports_credentials**: Allow authenticated requests when using CORS. + Default: disabled. +- **page_limit**: The number of items responses should be truncated to if the + client does not specify. Default ``500``. + + +.. _aura-cors: + +Cross-Origin Resource Sharing (CORS) +------------------------------------ + +`CORS`_ allows browser clients to make requests to the AURA server. You should +set the ``cors`` configuration option to a YAML list of allowed origins. + +For example:: + + aura: + cors: + - http://www.example.com + - https://aura.example.org + +Alternatively you can set it to ``'*'`` to enable access from all origins. +Note that there are security implications if you set the origin to ``'*'``, +so please research this before using it. Note the use of quote marks when +allowing all origins. Quote marks are also required when the origin is +``null``, for example when using ``file:///``. + +If the server is behind a proxy that uses credentials, you might want to set +the ``cors_supports_credentials`` configuration option to true to let +in-browser clients log in. Note that this option has not been tested, so it +may not work. + +.. _CORS: https://en.wikipedia.org/wiki/Cross-origin_resource_sharing + + +.. _aura-external-server: + +Using an External WSGI Server +----------------------------- + +If you would like to use a different WSGI server (not Flask's built-in one), +then you can! The ``beetsplug.aura`` module provides a WSGI callable called +``create_app()`` which can be used by many WSGI servers. + +For example to run the AURA server using `gunicorn`_ use +``gunicorn 'beetsplug.aura:create_app()'``, or for `uWSGI`_ use +``uwsgi --http :9090 --module 'beetsplug.aura:create_app()'``. +Note that these commands just show how to use the AURA app and you would +probably use something a bit different in a production environment. Read the +relevant server's documentation to figure out what you need. + +.. _gunicorn: https://gunicorn.org +.. _uWSGI: https://uwsgi-docs.readthedocs.io + + +Reverse Proxy Support +--------------------- + +The plugin should work behind a reverse proxy without further configuration, +however this has not been tested extensively. For details of what headers must +be rewritten and a sample NGINX configuration see `Flask proxy setups`_. + +It may be possibly to run the application under a URL prefix (for example so +you could have ``/foo/aura/server`` rather than ``/aura/server``), but it is +likely this would require changes in the code. + +Do not add a trailing slash (``/``) to the URL where the application is +running, otherwise you will get a 404. For example with NGINX you should use +``proxy_pass http://127.0.0.1:8000;`` rather than +``proxy_pass http://127.0.0.1:8000/;``. + +.. _Flask proxy setups: https://flask.palletsprojects.com/en/1.1.x/deploying/wsgi-standalone/#proxy-setups + + +.. _aura-issues: + +Issues +------ + +As of writing there are some differences between the specification and this +implementation: + +- Compound filters are not specified in AURA, but this server interprets + multiple ``filter`` parameters as AND. See `issue #19`_ for discussion. +- The ``bitrate`` parameter used for content negotiation is not supported. + Adding support for this is doable, but the way Flask handles acceptable MIME + types means it's a lot easier not to bother with it. This means an error + could be returned even if no transcoding was required. + +It is possible that some attributes required by AURA could be absent from the +server's response if beets does not have a saved value for them. However, this +has not happened so far. + +The ``mimetype`` and ``framecount`` attributes for track resources are not +supported. The first is due to beets storing the file type (e.g. ``MP3``), so +it is hard to filter by MIME type. The second is because there is no +corresponding beets field. + +Artists are defined by the ``artist`` field on beets Items, which means some +albums have no ``artists`` relationship. Albums only have related artists +when their beets ``albumartist`` field is the same as the ``artist`` field on +at least one of it's constituent tracks. + +The only art tracked by beets is a single cover image, so only albums have +related images at the moment. This could be expanded to looking in the same +directory for other images, and relating tracks to their album's image. + +There are likely to be some performance issues, especially with larger +libraries. Pagination and inclusion (most notably of images) are probably two +of the main offenders. On a related note, the program attempts to import Pillow +every time it constructs an image resource object, which is not very good. + +The beets library is accessed using a so called private function (with a single +leading underscore) ``beets.ui.__init__._open_library()``. This shouldn't cause +any issues but it is probably not best practice. + +.. _issue #19: https://github.com/beetbox/aura/issues/19 diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst index aab922fcd2..e28e2a2cf0 100644 --- a/docs/plugins/index.rst +++ b/docs/plugins/index.rst @@ -61,6 +61,7 @@ following to your configuration:: absubmit acousticbrainz + aura badfiles beatport bpd @@ -184,6 +185,7 @@ Path Formats Interoperability ---------------- +* :doc:`aura`: A server implementation of the `AURA`_ specification. * :doc:`badfiles`: Check audio file integrity. * :doc:`embyupdate`: Automatically notifies `Emby`_ whenever the beets library changes. * :doc:`fish`: Adds `Fish shell`_ tab autocompletion to ``beet`` commands. @@ -205,6 +207,7 @@ Interoperability library changes. +.. _AURA: https://auraspec.readthedocs.io .. _Emby: https://emby.media .. _Fish shell: https://fishshell.com/ .. _Plex: https://plex.tv From 51c3f310e91afb275de818d8f63c0563aef9a174 Mon Sep 17 00:00:00 2001 From: Callum Brown Date: Sun, 27 Sep 2020 18:09:16 +0100 Subject: [PATCH 02/14] AURA: Fix docstrings for tox -e lint --- beetsplug/aura.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/beetsplug/aura.py b/beetsplug/aura.py index 4269a4df8b..8050cc6217 100644 --- a/beetsplug/aura.py +++ b/beetsplug/aura.py @@ -14,8 +14,7 @@ # The above copyright notice and this permission notice shall be # included in all copies or substantial portions of the Software. -"""An AURA server using Flask. -""" +"""An AURA server using Flask.""" from __future__ import division, absolute_import, print_function @@ -811,7 +810,10 @@ def create_app(): class AURAPlugin(BeetsPlugin): + """The BeetsPlugin subclass for the AURA server plugin.""" + def __init__(self): + """Add configuration options for the AURA plugin.""" super(AURAPlugin, self).__init__() self.config.add( { @@ -824,6 +826,8 @@ def __init__(self): ) def commands(self): + """Add subcommand used to run the AURA server.""" + def run_aura(lib, opts, args): """Run the application using Flask's built in-server.""" app = create_app() From e8aa96ef72edd8e9a8ff3f0967fd0d0c1caabb8e Mon Sep 17 00:00:00 2001 From: Callum Brown Date: Sun, 27 Sep 2020 18:58:39 +0100 Subject: [PATCH 03/14] AURA: Add argument info to docstrings Follows the google docstring style: https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings --- beetsplug/aura.py | 188 ++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 157 insertions(+), 31 deletions(-) diff --git a/beetsplug/aura.py b/beetsplug/aura.py index 8050cc6217..f62dc29875 100644 --- a/beetsplug/aura.py +++ b/beetsplug/aura.py @@ -125,14 +125,25 @@ class AURADocument: @staticmethod def error(status, title, detail): - """Make a response for an error following the JSON:API spec.""" + """Make a response for an error following the JSON:API spec. + + Args: + status: An HTTP status code string, e.g. "404 Not Found". + title: A short, human-readable summary of the problem. + detail: A human-readable explanation specific to this + occurrence of the problem. + """ document = { "errors": [{"status": status, "title": title, "detail": detail}] } return make_response(document, status) def translate_attribute(self, aura_attr): - """Translate AURA attribute name to beets attribute name.""" + """Translate AURA attribute name to beets attribute name. + + Args: + aura_attr: The attribute name to convert, e.g. "title". + """ try: return self.attribute_map[aura_attr] except KeyError: @@ -161,7 +172,13 @@ def translate_filters(self): return AndQuery(queries) def translate_sorts(self, sort_arg): - """Translate an AURA sort parameter into a beets Sort.""" + """Translate an AURA sort parameter into a beets Sort. + + Args: + sort_arg: The value of the 'sort' query parameter; a comma + separated list of fields to sort by, in order. + E.g. "-year,title". + """ # Change HTTP query parameter to a list aura_sorts = sort_arg.strip(",").split(",") sorts = [] @@ -180,7 +197,13 @@ def translate_sorts(self, sort_arg): return MultipleSort(sorts) def paginate(self, collection): - """Get a page of the collection and the URL to the next page.""" + """Get a page of the collection and the URL to the next page. + + Args: + collection: The raw data from which resource objects can be + built. Could be an sqlite3.Cursor object (tracks and + albums) or a list of strings (artists). + """ # Pages start from zero page = request.args.get("page", 0, int) # Use page limit defined in config by default. @@ -213,8 +236,10 @@ def paginate(self, collection): def get_included(self, data, include_str): """Build a list of resource objects for inclusion. - :param data: Array of dicts in the form of resource objects - :param include_str: Comma separated list of resources to include + Args: + data: An array of dicts in the form of resource objects. + include_str: A comma separated list of resource types to + include. E.g. "tracks,images". """ # Change HTTP query parameter to a list to_include = include_str.strip(",").split(",") @@ -287,7 +312,12 @@ def all_resources(self): return document def single_resource_document(self, resource_object): - """Build document for a specific requested resource.""" + """Build document for a specific requested resource. + + Args: + resource_object: A dictionary in the form of a JSON:API + resource object. + """ document = {"data": resource_object} include_str = request.args.get("include", None) if include_str is not None: @@ -304,11 +334,20 @@ class TrackDocument(AURADocument): attribute_map = TRACK_ATTR_MAP def get_collection(self, query=None, sort=None): - """Get Item objects from the library.""" + """Get Item objects from the library. + + Args: + query: A beets Query object or a beets query string. + sort: A beets Sort object. + """ return current_app.config["lib"].items(query, sort) def get_attribute_converter(self, beets_attr): - """Work out what data type an attribute should be for beets.""" + """Work out what data type an attribute should be for beets. + + Args: + beets_attr: The name of the beets attribute, e.g. "title". + """ # filesize is a special field (read from disk not db?) if beets_attr == "filesize": converter = int @@ -325,7 +364,11 @@ def get_attribute_converter(self, beets_attr): @staticmethod def resource_object(track): - """Construct a JSON:API resource object from a beets Item.""" + """Construct a JSON:API resource object from a beets Item. + + Args: + track: A beets Item object. + """ attributes = {} # Use aura => beets attribute map, e.g. size => filesize for aura_attr, beets_attr in TRACK_ATTR_MAP.items(): @@ -353,7 +396,11 @@ def resource_object(track): } def single_resource(self, track_id): - """Get track from the library and build a document.""" + """Get track from the library and build a document. + + Args: + track_id: The beets id of the track (integer). + """ track = current_app.config["lib"].get_item(track_id) if track is None: return self.error( @@ -372,12 +419,20 @@ class AlbumDocument(AURADocument): attribute_map = ALBUM_ATTR_MAP def get_collection(self, query=None, sort=None): - """Get Album objects from the library.""" + """Get Album objects from the library. + + Args: + query: A beets Query object or a beets query string. + sort: A beets Sort object. + """ return current_app.config["lib"].albums(query, sort) def get_attribute_converter(self, beets_attr): - """Work out what data type an attribute should be for beets.""" - # filesize is a special field (read from disk not db?) + """Work out what data type an attribute should be for beets. + + Args: + beets_attr: The name of the beets attribute, e.g. "title". + """ try: # Look for field in list of Album fields # and get python type of database type. @@ -390,7 +445,11 @@ def get_attribute_converter(self, beets_attr): @staticmethod def resource_object(album): - """Construct a JSON:API resource object from a beets Album.""" + """Construct a JSON:API resource object from a beets Album. + + Args: + album: A beets Album object. + """ attributes = {} # Use aura => beets attribute name map for aura_attr, beets_attr in ALBUM_ATTR_MAP.items(): @@ -435,7 +494,11 @@ def resource_object(album): } def single_resource(self, album_id): - """Get album from the library and build a document.""" + """Get album from the library and build a document. + + Args: + album_id: The beets id of the album (integer). + """ album = current_app.config["lib"].get_album(album_id) if album is None: return self.error( @@ -454,7 +517,12 @@ class ArtistDocument(AURADocument): attribute_map = ARTIST_ATTR_MAP def get_collection(self, query=None, sort=None): - """Get a list of artist names from the library.""" + """Get a list of artist names from the library. + + Args: + query: A beets Query object or a beets query string. + sort: A beets Sort object. + """ # Gets only tracks with matching artist information tracks = current_app.config["lib"].items(query, sort) collection = [] @@ -465,7 +533,11 @@ def get_collection(self, query=None, sort=None): return collection def get_attribute_converter(self, beets_attr): - """Work out what data type an attribute should be for beets.""" + """Work out what data type an attribute should be for beets. + + Args: + beets_attr: The name of the beets attribute, e.g. "artist". + """ try: # Look for field in list of Item fields # and get python type of database type. @@ -478,7 +550,11 @@ def get_attribute_converter(self, beets_attr): @staticmethod def resource_object(artist_id): - """Construct a JSON:API resource object for the given artist.""" + """Construct a JSON:API resource object for the given artist. + + Args: + artist_id: A string which is the artist's name. + """ # Get tracks where artist field exactly matches artist_id query = MatchQuery("artist", artist_id) tracks = current_app.config["lib"].items(query) @@ -517,7 +593,11 @@ def resource_object(artist_id): } def single_resource(self, artist_id): - """Get info for the requested artist and build a document.""" + """Get info for the requested artist and build a document. + + Args: + artist_id: A string which is the artist's name. + """ artist_resource = self.resource_object(artist_id) if artist_resource is None: return self.error( @@ -538,7 +618,10 @@ def get_image_path(image_id): """Works out the full path to the image with the given id. Returns None if there is no such image. - image_id is in the form -- + + Args: + image_id: A string in the form + "--". """ # Split image_id into its constituent parts id_split = image_id.split("-") @@ -572,7 +655,12 @@ def get_image_path(image_id): @staticmethod def resource_object(image_id): - """Construct a JSON:API resource object for the given image.""" + """Construct a JSON:API resource object for the given image. + + Args: + image_id: A string in the form + "--". + """ # Could be called as a static method, so can't use # self.get_image_path() image_path = ImageDocument.get_image_path(image_id) @@ -609,7 +697,12 @@ def resource_object(image_id): } def single_resource(self, image_id): - """Get info for the requested image and build a document.""" + """Get info for the requested image and build a document. + + Args: + image_id: A string in the form + "--". + """ image_resource = self.resource_object(image_id) if image_resource is None: return self.error( @@ -644,14 +737,22 @@ def all_tracks(): @aura_bp.route("/tracks/") def single_track(track_id): - """Respond with info about the specified track.""" + """Respond with info about the specified track. + + Args: + track_id: The id of the track provided in the URL (integer). + """ doc = TrackDocument() return doc.single_resource(track_id) -@aura_bp.route("/tracks//audio") +@aura_bp.route("/tracks//audio") def audio_file(track_id): - """Supply an audio file for the specified track.""" + """Supply an audio file for the specified track. + + Args: + track_id: The id of the track provided in the URL (integer). + """ track = current_app.config["lib"].get_item(track_id) if track is None: return AURADocument.error( @@ -720,7 +821,11 @@ def all_albums(): @aura_bp.route("/albums/") def single_album(album_id): - """Respond with info about the specified album.""" + """Respond with info about the specified album. + + Args: + album_id: The id of the album provided in the URL (integer). + """ doc = AlbumDocument() return doc.single_resource(album_id) @@ -739,7 +844,12 @@ def all_artists(): # Using the path converter allows slashes in artist_id @aura_bp.route("/artists/") def single_artist(artist_id): - """Respond with info about the specified artist.""" + """Respond with info about the specified artist. + + Args: + artist_id: The id of the artist provided in the URL. A string + which is the artist's name. + """ doc = ArtistDocument() return doc.single_resource(artist_id) @@ -751,14 +861,24 @@ def single_artist(artist_id): @aura_bp.route("/images/") def single_image(image_id): - """Respond with info about the specified image.""" + """Respond with info about the specified image. + + Args: + image_id: The id of the image provided in the URL. A string in + the form "--". + """ doc = ImageDocument() return doc.single_resource(image_id) @aura_bp.route("/images//file") def image_file(image_id): - """Supply an image file for the specified image.""" + """Supply an image file for the specified image. + + Args: + image_id: The id of the image provided in the URL. A string in + the form "--". + """ img_path = ImageDocument.get_image_path(image_id) if img_path is None: return AURADocument.error( @@ -829,7 +949,13 @@ def commands(self): """Add subcommand used to run the AURA server.""" def run_aura(lib, opts, args): - """Run the application using Flask's built in-server.""" + """Run the application using Flask's built in-server. + + Args: + lib: A beets Library object (not used). + opts: Command line options. An optparse.Values object. + args: The list of arguments to process (not used). + """ app = create_app() # Start the built-in server (not intended for production) app.run( From e067298224fa983b0bf957bbb8595c9746f7f7ae Mon Sep 17 00:00:00 2001 From: Callum Brown Date: Wed, 28 Oct 2020 18:53:39 +0000 Subject: [PATCH 04/14] Add default config values in create_app() So if not run through beet aura then default values will be available --- beetsplug/aura.py | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/beetsplug/aura.py b/beetsplug/aura.py index f62dc29875..6cc965b21b 100644 --- a/beetsplug/aura.py +++ b/beetsplug/aura.py @@ -896,6 +896,16 @@ def image_file(image_id): def create_app(): """An application factory for use by a WSGI server.""" + config["aura"].add( + { + "host": u"127.0.0.1", + "port": 8337, + "cors": [], + "cors_supports_credentials": False, + "page_limit": 500, + } + ) + app = Flask(__name__) # Register AURA blueprint view functions under a URL prefix app.register_blueprint(aura_bp, url_prefix="/aura") @@ -935,15 +945,6 @@ class AURAPlugin(BeetsPlugin): def __init__(self): """Add configuration options for the AURA plugin.""" super(AURAPlugin, self).__init__() - self.config.add( - { - "host": u"127.0.0.1", - "port": 8337, - "cors": [], - "cors_supports_credentials": False, - "page_limit": 500, - } - ) def commands(self): """Add subcommand used to run the AURA server.""" From 72c041255244b8fc767f30079ae643a881e4e618 Mon Sep 17 00:00:00 2001 From: Callum Brown Date: Fri, 30 Oct 2020 12:27:22 +0000 Subject: [PATCH 05/14] AURA: Small updates to documentation --- docs/plugins/aura.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/plugins/aura.rst b/docs/plugins/aura.rst index 2891d25e18..1cadb45db5 100644 --- a/docs/plugins/aura.rst +++ b/docs/plugins/aura.rst @@ -69,8 +69,8 @@ Configuration To configure the plugin, make an ``aura:`` section in your configuration file. The available options are: -- **host**: The server hostname. Set this to 0.0.0.0 to bind to all interfaces. - Default: ``127.0.0.1``. +- **host**: The server hostname. Set this to ``0.0.0.0`` to bind to all + interfaces. Default: ``127.0.0.1``. - **port**: The server port. Default: ``8337``. - **cors**: A YAML list of origins to allow CORS requests from (see @@ -122,7 +122,7 @@ then you can! The ``beetsplug.aura`` module provides a WSGI callable called For example to run the AURA server using `gunicorn`_ use ``gunicorn 'beetsplug.aura:create_app()'``, or for `uWSGI`_ use -``uwsgi --http :9090 --module 'beetsplug.aura:create_app()'``. +``uwsgi --http :8337 --module 'beetsplug.aura:create_app()'``. Note that these commands just show how to use the AURA app and you would probably use something a bit different in a production environment. Read the relevant server's documentation to figure out what you need. @@ -144,8 +144,8 @@ likely this would require changes in the code. Do not add a trailing slash (``/``) to the URL where the application is running, otherwise you will get a 404. For example with NGINX you should use -``proxy_pass http://127.0.0.1:8000;`` rather than -``proxy_pass http://127.0.0.1:8000/;``. +``proxy_pass http://127.0.0.1:8337;`` rather than +``proxy_pass http://127.0.0.1:8337/;``. .. _Flask proxy setups: https://flask.palletsprojects.com/en/1.1.x/deploying/wsgi-standalone/#proxy-setups @@ -184,9 +184,9 @@ related images at the moment. This could be expanded to looking in the same directory for other images, and relating tracks to their album's image. There are likely to be some performance issues, especially with larger -libraries. Pagination and inclusion (most notably of images) are probably two -of the main offenders. On a related note, the program attempts to import Pillow -every time it constructs an image resource object, which is not very good. +libraries. Sorting, pagination and inclusion (most notably of images) are +probably the main offenders. On a related note, the program attempts to import +Pillow every time it constructs an image resource object, which is not good. The beets library is accessed using a so called private function (with a single leading underscore) ``beets.ui.__init__._open_library()``. This shouldn't cause From c2a92fdbf8849fdd558afb8c5df9c5f13d94333c Mon Sep 17 00:00:00 2001 From: Callum Brown Date: Sat, 21 Nov 2020 18:40:44 +0000 Subject: [PATCH 06/14] AURA: Update reverse proxy docs --- docs/plugins/aura.rst | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/plugins/aura.rst b/docs/plugins/aura.rst index 1cadb45db5..7af8b19e62 100644 --- a/docs/plugins/aura.rst +++ b/docs/plugins/aura.rst @@ -138,14 +138,13 @@ The plugin should work behind a reverse proxy without further configuration, however this has not been tested extensively. For details of what headers must be rewritten and a sample NGINX configuration see `Flask proxy setups`_. -It may be possibly to run the application under a URL prefix (for example so -you could have ``/foo/aura/server`` rather than ``/aura/server``), but it is -likely this would require changes in the code. - -Do not add a trailing slash (``/``) to the URL where the application is -running, otherwise you will get a 404. For example with NGINX you should use -``proxy_pass http://127.0.0.1:8337;`` rather than -``proxy_pass http://127.0.0.1:8337/;``. +It is (reportedly) possible to run the application under a URL prefix (for +example so you could have ``/foo/aura/server`` rather than ``/aura/server``), +but you'll have to work it out for yourself :-) + +If using NGINX, do **not** add a trailing slash (``/``) to the URL where the +application is running, otherwise you will get a 404. However if you are using +Apache then you **should** add a trailing slash. .. _Flask proxy setups: https://flask.palletsprojects.com/en/1.1.x/deploying/wsgi-standalone/#proxy-setups From 7e819d2a2eb06c7142622b29109c7593dbcbe90a Mon Sep 17 00:00:00 2001 From: Callum Brown Date: Sat, 6 Mar 2021 12:01:02 +0000 Subject: [PATCH 07/14] AURA: Update artist-mbid attribute to use '-' --- beetsplug/aura.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/beetsplug/aura.py b/beetsplug/aura.py index 6cc965b21b..60507b78f2 100644 --- a/beetsplug/aura.py +++ b/beetsplug/aura.py @@ -116,7 +116,7 @@ # Required "name": "artist", # Optional - "artist_mbid": "mb_artistid", + "artist-mbid": "mb_artistid", } From b1baeb37f1d3e563b5de6f0f8ea068768fa4d797 Mon Sep 17 00:00:00 2001 From: Callum Brown Date: Sat, 6 Mar 2021 12:08:35 +0000 Subject: [PATCH 08/14] AURA: replace translate_attribute with a dict.get --- beetsplug/aura.py | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) diff --git a/beetsplug/aura.py b/beetsplug/aura.py index 60507b78f2..536448d582 100644 --- a/beetsplug/aura.py +++ b/beetsplug/aura.py @@ -138,18 +138,6 @@ def error(status, title, detail): } return make_response(document, status) - def translate_attribute(self, aura_attr): - """Translate AURA attribute name to beets attribute name. - - Args: - aura_attr: The attribute name to convert, e.g. "title". - """ - try: - return self.attribute_map[aura_attr] - except KeyError: - # Assume native beets attribute - return aura_attr - def translate_filters(self): """Translate filters from request arguments to a beets Query.""" # The format of each filter key in the request parameter is: @@ -162,7 +150,7 @@ def translate_filters(self): # Extract attribute name from key aura_attr = match.group("attribute") # Get the beets version of the attribute name - beets_attr = self.translate_attribute(aura_attr) + beets_attr = self.attribute_map.get(aura_attr, aura_attr) converter = self.get_attribute_converter(beets_attr) value = converter(value) # Add exact match query to list @@ -191,7 +179,7 @@ def translate_sorts(self, sort_arg): # JSON:API default ascending = True # Get the beets version of the attribute name - beets_attr = self.translate_attribute(aura_attr) + beets_attr = self.attribute_map.get(aura_attr, aura_attr) # Use slow sort so it works with all fields (inc. computed) sorts.append(SlowFieldSort(beets_attr, ascending=ascending)) return MultipleSort(sorts) From 07cfaaa3b378afa1f8be43a91ebccad29e1650e2 Mon Sep 17 00:00:00 2001 From: Callum Brown Date: Sat, 6 Mar 2021 12:25:33 +0000 Subject: [PATCH 09/14] AURA: Simplify if statements Get rid of ` is not None` Change `len(x) == 0` to `not x` Change `x is None` to `not x` --- beetsplug/aura.py | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/beetsplug/aura.py b/beetsplug/aura.py index 536448d582..5a949dcf6e 100644 --- a/beetsplug/aura.py +++ b/beetsplug/aura.py @@ -146,7 +146,7 @@ def translate_filters(self): queries = [] for key, value in request.args.items(): match = pattern.match(key) - if match is not None: + if match: # Extract attribute name from key aura_attr = match.group("attribute") # Get the beets version of the attribute name @@ -206,10 +206,10 @@ def paginate(self, collection): next_url = None else: # Not the last page so work out links.next url - if len(request.args) == 0: + if not request.args: # No existing arguments, so current page is 0 next_url = request.url + "?page=1" - elif request.args.get("page", None) is None: + elif not request.args.get("page", None): # No existing page argument, so add one to the end next_url = request.url + "&page=1" else: @@ -272,7 +272,7 @@ def all_resources(self): """Build document for /tracks, /albums or /artists.""" query = self.translate_filters() sort_arg = request.args.get("sort", None) - if sort_arg is not None: + if sort_arg: sort = self.translate_sorts(sort_arg) # For each sort field add a query which ensures all results # have a non-empty, non-zero value for that field. @@ -291,11 +291,11 @@ def all_resources(self): data, next_url = self.paginate(collection) document = {"data": data} # If there are more pages then provide a way to access them - if next_url is not None: + if next_url: document["links"] = {"next": next_url} # Include related resources for each element in "data" include_str = request.args.get("include", None) - if include_str is not None: + if include_str: document["included"] = self.get_included(data, include_str) return document @@ -308,7 +308,7 @@ def single_resource_document(self, resource_object): """ document = {"data": resource_object} include_str = request.args.get("include", None) - if include_str is not None: + if include_str: # [document["data"]] is because arg needs to be list document["included"] = self.get_included( [document["data"]], include_str @@ -390,7 +390,7 @@ def single_resource(self, track_id): track_id: The beets id of the track (integer). """ track = current_app.config["lib"].get_item(track_id) - if track is None: + if not track: return self.error( "404 Not Found", "No track with the requested id.", @@ -459,7 +459,7 @@ def resource_object(album): } } # Add images relationship if album has associated images - if album.artpath is not None: + if album.artpath: path = displayable_path(album.artpath) filename = path.split("/")[-1] image_id = "album-{}-{}".format(album.id, filename) @@ -488,7 +488,7 @@ def single_resource(self, album_id): album_id: The beets id of the album (integer). """ album = current_app.config["lib"].get_album(album_id) - if album is None: + if not album: return self.error( "404 Not Found", "No album with the requested id.", @@ -546,7 +546,7 @@ def resource_object(artist_id): # Get tracks where artist field exactly matches artist_id query = MatchQuery("artist", artist_id) tracks = current_app.config["lib"].items(query) - if len(tracks) == 0: + if not tracks: return None # Get artist information from the first track @@ -587,7 +587,7 @@ def single_resource(self, artist_id): artist_id: A string which is the artist's name. """ artist_resource = self.resource_object(artist_id) - if artist_resource is None: + if not artist_resource: return self.error( "404 Not Found", "No artist with the requested id.", @@ -623,7 +623,7 @@ def get_image_path(image_id): # Get the path to the directory parent's images are in if parent_type == "album": album = current_app.config["lib"].get_album(int(parent_id)) - if album is None or album.artpath is None: + if not album or not album.artpath: return None # Cut the filename off of artpath # This is in preparation for supporting images in the same @@ -652,7 +652,7 @@ def resource_object(image_id): # Could be called as a static method, so can't use # self.get_image_path() image_path = ImageDocument.get_image_path(image_id) - if image_path is None: + if not image_path: return None attributes = { @@ -692,7 +692,7 @@ def single_resource(self, image_id): "--". """ image_resource = self.resource_object(image_id) - if image_resource is None: + if not image_resource: return self.error( "404 Not Found", "No image with the requested id.", @@ -742,7 +742,7 @@ def audio_file(track_id): track_id: The id of the track provided in the URL (integer). """ track = current_app.config["lib"].get_item(track_id) - if track is None: + if not track: return AURADocument.error( "404 Not Found", "No track with the requested id.", @@ -762,7 +762,7 @@ def audio_file(track_id): ) file_mimetype = guess_type(path)[0] - if file_mimetype is None: + if not file_mimetype: return AURADocument.error( "500 Internal Server Error", "Requested audio file has an unknown mimetype.", @@ -777,7 +777,7 @@ def audio_file(track_id): # Adding support for the bitrate parameter would require some effort so I # left it out. This means the client could be sent an error even if the # audio doesn't need transcoding. - if request.accept_mimetypes.best_match([file_mimetype]) is None: + if not request.accept_mimetypes.best_match([file_mimetype]): return AURADocument.error( "406 Not Acceptable", "Unsupported MIME type or bitrate parameter in Accept header.", @@ -868,7 +868,7 @@ def image_file(image_id): the form "--". """ img_path = ImageDocument.get_image_path(image_id) - if img_path is None: + if not img_path: return AURADocument.error( "404 Not Found", "No image with the requested id.", From fbc76887ad11d67c7a0262f8626c094eca62ff4b Mon Sep 17 00:00:00 2001 From: Callum Brown Date: Sat, 6 Mar 2021 13:22:28 +0000 Subject: [PATCH 10/14] AURA: Fix styling when formatting error strings --- beetsplug/aura.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/beetsplug/aura.py b/beetsplug/aura.py index 5a949dcf6e..8980885fd3 100644 --- a/beetsplug/aura.py +++ b/beetsplug/aura.py @@ -394,7 +394,7 @@ def single_resource(self, track_id): return self.error( "404 Not Found", "No track with the requested id.", - ("There is no track with an id of {} in the library.").format( + "There is no track with an id of {} in the library.".format( track_id ), ) @@ -492,7 +492,7 @@ def single_resource(self, album_id): return self.error( "404 Not Found", "No album with the requested id.", - ("There is no album with an id of {} in the library.").format( + "There is no album with an id of {} in the library.".format( album_id ), ) @@ -591,7 +591,7 @@ def single_resource(self, artist_id): return self.error( "404 Not Found", "No artist with the requested id.", - ("There is no artist with an id of {} in the library.").format( + "There is no artist with an id of {} in the library.".format( artist_id ), ) @@ -696,7 +696,7 @@ def single_resource(self, image_id): return self.error( "404 Not Found", "No image with the requested id.", - ("There is no image with an id of {} in the library.").format( + "There is no image with an id of {} in the library.".format( image_id ), ) @@ -746,7 +746,7 @@ def audio_file(track_id): return AURADocument.error( "404 Not Found", "No track with the requested id.", - ("There is no track with an id of {} in the library.").format( + "There is no track with an id of {} in the library.".format( track_id ), ) @@ -768,7 +768,7 @@ def audio_file(track_id): "Requested audio file has an unknown mimetype.", ( "The audio file for track {} has an unknown mimetype. " - "It's file extension is {}." + "Its file extension is {}." ).format(track_id, path.split(".")[-1]), ) @@ -872,7 +872,7 @@ def image_file(image_id): return AURADocument.error( "404 Not Found", "No image with the requested id.", - ("There is no image with an id of {} in the library").format( + "There is no image with an id of {} in the library".format( image_id ), ) From 2fe2f4f31eb2ca70128e4739bb849847c1bebea4 Mon Sep 17 00:00:00 2001 From: Callum Brown Date: Sat, 6 Mar 2021 13:30:31 +0000 Subject: [PATCH 11/14] AURA: Ensure CORS allowed origins are strings --- beetsplug/aura.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/beetsplug/aura.py b/beetsplug/aura.py index 8980885fd3..201e099e35 100644 --- a/beetsplug/aura.py +++ b/beetsplug/aura.py @@ -909,7 +909,7 @@ def create_app(): app.config["lib"] = _open_library(config) # Enable CORS if required - cors = config["aura"]["cors"].get(list) + cors = config["aura"]["cors"].as_str_seq(list) if cors: from flask_cors import CORS From 477eed3b25c8983b77e59f259891dd536289a378 Mon Sep 17 00:00:00 2001 From: Callum Brown Date: Sun, 7 Mar 2021 10:25:20 +0000 Subject: [PATCH 12/14] AURA: Use py3_path rather than displayable_path displayable_path may remove 'bad' characters, yielding a wrong path. Also use track.path rather than track.destination() as that is where the file is actually located rather than where it should be located according to the beets path system. --- beetsplug/aura.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/beetsplug/aura.py b/beetsplug/aura.py index 201e099e35..f3f8980aec 100644 --- a/beetsplug/aura.py +++ b/beetsplug/aura.py @@ -25,7 +25,7 @@ from beets.plugins import BeetsPlugin from beets.ui import Subcommand, _open_library from beets import config -from beets.util import displayable_path +from beets.util import py3_path from beets.library import Item, Album from beets.dbcore.query import ( MatchQuery, @@ -460,7 +460,7 @@ def resource_object(album): } # Add images relationship if album has associated images if album.artpath: - path = displayable_path(album.artpath) + path = py3_path(album.artpath) filename = path.split("/")[-1] image_id = "album-{}-{}".format(album.id, filename) relationships["images"] = { @@ -628,7 +628,7 @@ def get_image_path(image_id): # Cut the filename off of artpath # This is in preparation for supporting images in the same # directory that are not tracked by beets. - artpath = displayable_path(album.artpath) + artpath = py3_path(album.artpath) dir_path = "/".join(artpath.split("/")[:-1]) else: # Images for other resource types are not supported @@ -751,7 +751,7 @@ def audio_file(track_id): ), ) - path = displayable_path(track.destination()) + path = py3_path(track.path) if not isfile(path): return AURADocument.error( "404 Not Found", From a54ee43d57a2b3b6913bb8827b3fda8b63449d61 Mon Sep 17 00:00:00 2001 From: Callum Brown Date: Sun, 7 Mar 2021 14:23:17 +0000 Subject: [PATCH 13/14] AURA: Allow '-' character in filter attribute --- beetsplug/aura.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/beetsplug/aura.py b/beetsplug/aura.py index f3f8980aec..f0cda3688c 100644 --- a/beetsplug/aura.py +++ b/beetsplug/aura.py @@ -142,7 +142,7 @@ def translate_filters(self): """Translate filters from request arguments to a beets Query.""" # The format of each filter key in the request parameter is: # filter[]. This regex extracts . - pattern = re.compile(r"filter\[(?P\w+)\]") + pattern = re.compile(r"filter\[(?P[a-zA-Z0-9_-]+)\]") queries = [] for key, value in request.args.items(): match = pattern.match(key) From a24a094562960b952edff464406e26e50d436421 Mon Sep 17 00:00:00 2001 From: Callum Brown Date: Sun, 7 Mar 2021 18:24:57 +0000 Subject: [PATCH 14/14] AURA: Small updates to docs and set server version --- beetsplug/aura.py | 2 +- docs/changelog.rst | 1 + docs/plugins/aura.rst | 8 ++++++-- 3 files changed, 8 insertions(+), 3 deletions(-) diff --git a/beetsplug/aura.py b/beetsplug/aura.py index f0cda3688c..df76ca8569 100644 --- a/beetsplug/aura.py +++ b/beetsplug/aura.py @@ -54,7 +54,7 @@ SERVER_INFO = { "aura-version": "0", "server": "beets-aura", - "server-version": "0", + "server-version": "0.1", "auth-required": False, "features": ["albums", "artists", "images"], } diff --git a/docs/changelog.rst b/docs/changelog.rst index 2f31ecfe36..090c5b6f7a 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -183,6 +183,7 @@ New features: * Added ``trackdisambig`` which stores the recording disambiguation from MusicBrainz for each track. :bug:`1904` +* The :doc:`/plugins/aura` has arrived! Fixes: diff --git a/docs/plugins/aura.rst b/docs/plugins/aura.rst index 7af8b19e62..83c1862497 100644 --- a/docs/plugins/aura.rst +++ b/docs/plugins/aura.rst @@ -48,8 +48,7 @@ then see :ref:`aura-external-server`. AURA is designed to separate the client and server functionality. This plugin provides the server but not the client, so unless you like looking at JSON you -will need a separate client. Unfortunately there are no AURA clients yet -(discounting the broken and outdated reference implementation). +will need a separate client. Currently the only client is `AURA Web Client`_. By default the API is served under http://127.0.0.1:8337/aura/. For example information about the track with an id of 3 can be obtained at @@ -59,6 +58,7 @@ http://127.0.0.1:8337/aura/tracks/3. http://127.0.0.1:8337/aura/tracks/3/ returns a ``404 Not Found`` error. .. _development mode: https://flask.palletsprojects.com/en/1.1.x/server +.. _AURA Web Client: https://sr.ht/~callum/aura-web-client/ .. _configuration: @@ -168,6 +168,10 @@ It is possible that some attributes required by AURA could be absent from the server's response if beets does not have a saved value for them. However, this has not happened so far. +Beets fields (including flexible fields) that do not have an AURA equivalent +are not provided in any resource's attributes section, however these fields may +be used for filtering. + The ``mimetype`` and ``framecount`` attributes for track resources are not supported. The first is due to beets storing the file type (e.g. ``MP3``), so it is hard to filter by MIME type. The second is because there is no