nup-headless

nup-headless executable

This daemon can be run on a headless computer connected to an audio system. It exposes the same web interface as the App Engine server, but it plays music locally and reports plays to App Engine. Web clients send requests and receive events via WebSocket connections.

Usage

Usage: nup-headless [flag]...
HTTP server for playing music locally.

  -config string
    	Path to YAML config file (default "$HOME/.nup-headless.yaml")
  -debug
    	Log extra debugging info
  -log-timestamps
    	Prefix log messages with timestamps (default true)

At startup, nup-headless reads a YAML-marshaled Config struct from the file specified via the -config flag.

HTTP endpoints

The following HTTP endpoints are proxied to the App Engine server:

• /cover
• /dump_song
• /presets
• /query
• /rate_and_tag (only permitted for non-guest users)
• /share
• /stats
• /tags

nup-headless provides its own implementation of the /user endpoint that returns information about the currently-authenticated user from the nup-headless configuration.

The /ws endpoint is used for establishing WebSocket connections.

WebSocket requests sent by web clients

These JSON-marshaled messages are sent from web clients to nup-headless.

In addition to the properties described below, every message contains a type property with the request type, e.g. enqueue_songs.

enqueue_songs

Adds one or more songs to the playlist.

• action - String specifying where songs should be enqueued (append, insert, or replace).
• songs - Array of Song objects to add.

get_state

Requests that a state event be sent to the client.

pause

Pauses playback.

ping

Requests that a pong event be sent to the client.

• pingId - Integer ID to include in the pong event.

play

Unpauses playback. If playback is stopped at the end of the last song in the playlist, replays the song.

remove_songs

Removes one or more songs from the playlist.

• len - Integer number of songs to remove.
• start - Integer 0-based index of the first song to remove.

reorder_song

Moves a song to a different position in the playlist.

• from - Integer 0-based index of song to move.
• to - Integer 0-based destination index.

seek

Changes the playback position in the current song.

• seconds - Float position offset in seconds.

select_track

Selects a song in the playlist.

• delayPlay - Boolean indicating that nup-headless should briefly wait before downloading the song and starting playback. Used when cycling between tracks.
• index - Integer 0-based index of song to play.

set_option

Changes a runtime option.

• name - String option name.
• value - String option value.

Available options:

• gainType - String describing how song volumes should be adjusted (album, auto, none, or track).
• preAmp - Float volume adjustment in decibels.

set_play_delay

Configures the delay before starting playback in response to select_track requests with delayPlay set to true. Used by tests.

• delayMs - Integer delay in milliseconds.

WebSocket events sent to web clients

These JSON-marshaled messages are sent from nup-headless to web clients.

In addition to the properties described below, every message contains the following properties:

• type - String event type, e.g. current_index_changed.
• broadcastId - Current broadcast ID held in the server. This is incremented with each broadcast event that is sent to all clients (i.e. all events but pong and state). Clients can use this to detect dropped broadcast events.

current_index_changed

Broadcast to all clients when the index of the current-active song in the playlist changes.

• currentIndex - Integer 0-based index of current song.

option_changed

Broadcast to all clients when a runtime option changes.

• name - String option name (see set_option request).
• value - String option value (see set_option request).

play_state_changed

Broadcast to all clients when the playback state (e.g. playing or paused) changes.

• playState - String playback state (paused, play, playing, or stopped).

pong

Sent to a single client in response to a ping request.

• pingId - Integer ID included in the original ping request.

position_changed

Broadcast to all clients when the playback position changes.

• position - Float playback position in seconds.

song_modified

Broadcast to all clients when a song is rated or tagged.

• song - Song containing updated data.

songs_changed

Broadcast to all clients when the songs in the playlist change.

• currentIndex - Integer 0-based index of the current song.
• songs - Array of Songs in the playlist.

state

Sent to single client in response to a get_state request.

• buildTimestamp - Opaque string build timestamp of the nup-headless binary. Comparable to the buildTimestamp string injected into the web interface, and omitted if the build time was not recorded.
• currentIndex - Integer 0-based index of the current song.
• options - Object containing runtime option name-to-value mappings (see set_option request).
• playState - String playback state (see play_state_changed event).
• position - Float playback position in seconds.
• songs - Array of Songs in the playlist.