server

nup Google App Engine server

HTTP endpoints

/ (GET)

Returns the index page.

/clear (POST, dev-only)

Deletes all song and play objects from Datastore. Used by tests.

/config (POST, dev-only)

Modifies server behavior. Used by tests.

• forceUpdateFailures (optional) - If 1, report failures for all user data updates (ratings, tags, plays).

/cover (GET)

Returns an album cover art image.

• filename - Image path from Song's CoverFilename field.
• format (optional) - If avif or webp, avif return a prescaled AVIF or WebP version of the image if available. If unavailable, dynamically scale the image and preserve its original format (i.e. JPEG or PNG).
• scale (optional) - Scaling function to use. See coverScalers in main.go for possible values.
• size (optional) - Integer dimension in pixels to scale the image to. Images are never upscaled and aspect ratios are preserved. For example, given a size of 512, a 1030x1024 image will be scaled to 515x512.

/delete_song (POST)

Deletes a song from Datastore.

• songId - Integer ID from Song's SongID field.

/dump_song (GET)

Returns a JSON-marshaled Song object. Plays are included.

• songId - Integer ID from Song's SongID field.

/export (GET)

Returns a series of JSON-marshaled Song or Play objects, followed by an optional JSON string containing a cursor for the next batch if not all objects were returned. Objects are typically ordered by ascending integer song ID, but if minLastModifiedNsec or minStartTimeNsec are supplied, they're instead ordered by the corresponding fields due to Datastore limitations.

• cursor (optional) - Cursor to continue an earlier request.
• max (optional) - Integer maximum number of items to return.
• type - Type of entity to export (song or play).

Several parameters are only relevant for the song type:

• deleted (optional) - If 1, return deleted songs rather than non-deleted songs.
• minLastModifiedNsec (optional) - Integer nanoseconds since Unix epoch of songs' last-modified timestamps. Used for incremental updates.
• omit (optional) - Comma-separated list of Song fields to clear. Available fields are coverFilename, plays, and sha1.

Other parameters are only relevant for the play type:

• minReportTimeNsec (optional) - Integer nanoseconds since Unix epoch of plays' report timestamps. Used for incremental exports.
• minStartTimeNsec (optional) - Integer nanoseconds since Unix epoch of plays' start-time timestamps. Used for incremental exports.

/flush_cache (POST, dev-only)

Flushes data cached in Memcache (and possibly also in Datastore). Used by tests.

• onlyMemcache (optional) - If 1, don't flush the Datastore cache.

/import (POST)

Imports a stream (not an array) of JSON-marshaled Song and Play objects into Datastore.

• replaceUserData (optional) - If 1, replace the songs' existing user data in Datastore (ratings, tags, play history) with user data from the supplied songs. Otherwise, the existing data is preserved.
• updateDelayNsec (optional) - Integer value containing nanoseconds to wait before writing to Datastore. Used by tests.
• useFilenames (optional) - If 1, identify songs by filenames rather than hashes of their audio data. This is useful after updating a file's data (e.g. to correct errors): as long as its path renames the same, the existing entity will be updated rather than a new one being inserted.

Returns a JSON-marshaled ImportResponse object.

/now (GET)

Returns the server's current time as integer nanoseconds since the Unix epoch.

/played (POST)

Records a single play of a song in Datastore. Also saves the reporter's IP address.

• songId - Integer ID from Song's SongID field.
• startTime - RFC 3339 string specifying when playback of the song started. Float seconds since the Unix epoch are also accepted.

/presets (GET)

Returns a JSON-marshaled array of SearchPreset objects describing search presets that can be used by clients. If the server's configuration specified custom presets for the requesting user, they are returned instead of the default presets.

/query (GET)

Queries Datastore and returns a JSON-marshaled array of Songs.

• album (optional) - String album name.
• albumId (optional) - String album ID from MusicBrainz Album Id field, e.g. 124f4108-fec8-4663-b69c-19b37ff1703c.
• artist (optional) - String artist name.
• cacheOnly (optional) - If 1, only return cached data. Used by tests.
• keywords (optional) - Space-separated keywords to match against artists, titles, and albums.
• fallback (optional) - If force, only uses the fallback mode that tries to avoid using composite indexes in Datastore. If never, doesn't use the fallback mode at all. Used by tests.
• filename (optional) - String song filename relative to music directory.
• firstTrack (optional) - If 1, only returns songs that are the first tracks of first discs.
• maxDate (optional) - RFC 3339 string containing maximum song date.
• maxLastPlayed (optional) - RFC 3339 string specifying the maximum time at which songs were last played (to select music that hasn't been played recently). Float seconds since the Unix epoch are also accepted.
• maxPlays (optional) - Integer maximum number of plays.
• maxRating (optional) - Integer maximum song rating in the range [1, 5]. Unrated songs are not returned when this parameter is supplied.
• maxResults (optional) - Integer maximum number of songs to return. The server still caps queries to 100 songs. Used by tests.
• minDate (optional) - RFC 3339 string containing minimum song date.
• minFirstPlayed (optional) - RFC 3339 string specifying the minimum time at which songs were first played (to select recently-added music). Float seconds since the Unix epoch are also accepted.
• minRating (optional) - Integer minimum song rating in the range [1, 5].
• onlyIds (optional) - If 1, return a JSON-marshaled array of string Song.SongID values rather than the Song objects themselves. The results will not be properly sorted or shuffled in this case (but they will be ordered correctly if orderByLastPlayed was passed).
• orderByLastPlayed (optional) - If 1, return songs that were last played the longest ago.
• rating (optional) - Integer song rating in the range [1, 5].
• sha1 (optional) - String SHA1 of song to return.
• songId (optional) - Integer ID (i.e. datastore key) of song to return.
• shuffle (optional) - If 1, shuffle the order of returned songs.
• stats (option) - If 1, return an object with a results array property and a numMatched int property.
• unrated (optional) - If 1, return only songs that have no rating.
• tags (optional) - Space-separated tags, e.g. electronic -vocals. Returned songs will have all of the supplied positive tags and none of the supplied negative --prefixed tags. A single positive "or" tag set can contain pipe-separated tags, e.g. rock|folk|jazz. Multiple negative tag sets can be supplied, e.g. -annoying|loud|obnoxious -cheery|upbeat.
• title (optional) - String song title.

/rate_and_tag (POST)

Updates a song's rating and/or tags in Datastore and returns the updated Song object, marshaled to JSON.

• addTags (optional) - Space-separated tags to add to the song's current set. Ignored if tags is supplied.
• rating (optional) - Integer rating for the song in the range [1, 5], or 0 to clear the song's rating. See Song's Rating field.
• songId - Integer ID from Song's SongID field.
• tags (optional) - Full list of space-separated tags for the song. See Song's Tags field.
• removeTags (optional) - Space-separated tags to remove from the song's current set. Ignored if tags is supplied.
• updateDelayNsec (optional) - Integer value containing nanoseconds to wait before writing to Datastore. Used by tests.

/reindex (POST)

Regenerates fields used for searching across all Song objects.

• cursor (optional) - Query cursor returned by previous call.

Returns a JSON-marshaled ReindexResponse object.

/share (GET)

Redirects to a web+nup:view URL that can be handled by Android intent filters or web protocol handlers. Query parameters are preserved.

• albumId (optional) - String from Song's AlbumID field.
• artist (optional) - String corresponding to Song's Artist field.
• songId (optional) - Integer ID from Song's SongID field.

/song (GET)

Returns a song's MP3 data.

• filename - MP3 path from Song's Filename field.

/stats (GET)

Gets periodically-computed stats about the database. Returns a JSON-marshaled Stats object.

• live - If 1, return live stats instead periodically-computed stats. Only the Songs, Plays, and UpdateTime fields will be set.
• update - If 1, update stats instead of getting them. Called periodically by cron.

/tags (GET)

Returns a JSON-marshaled array of strings containing known tags. Tags are sorted by descending frequency and then lexicographically.

• requireCache (optional) - If 1, only return cached data. Used by tests.

/user (GET)

Returns a JSON-marshaled User object containing information about the requesting user.