Extensions

• 1: API Key Authentication
• 2: HTTP form POST
• 3: Song Lyrics
• 4: Template extension
• 5: Transcode Offset

1 - API Key Authentication

OpenSubsonic version: 1

OpenSubsonic extension name apiKeyAuthentication (As returned by getOpenSubsonicExtensions)

Version 1

This extension requires changes to the semantics of authentication. Broadly, there are two general changes:

1. Required: A new authentication mechanism: apiKey for query.
2. Recommended: Deprecation of token/salt-based authentication.

API keys

An API key is any authentication token generated by an OpenSubsonic server that can be used to authenticate. How this API key is generated by the server is implementation-specific: the server may provide a page where the user can configure one or more API keys, the server may automatically generate a API key, or any other variety of means. The format of the API key is not specified, but it must be of reasonable length to fit into a query parameter (less than 2048 characters URL-encoded).

Servers which implement this extension must provide some mechanism for viewing active API key(s) and allow for revoking API keys. Note that these API keys do not expire; as long as they are not revoked by the user, they are assumed to be valid.

Using a API key

An API key is used as a query parameter apiKey=<api key>. When an API key is provided, the client must not provide a u parameter; passing in u must be treated as an error 43.

It is recommended that servers which provide API-key authentication no longer support salt/token-based authentication.

If multiple conflicting authentication parameters are passed in, the server must return an error 43, Multiple conflicting authentication mechanisms provided

If a server removes support for token-based authentication, it must return error 41 (Token authentication not supported for LDAP users.).

If a server removes support for any other particular authentication mechanism, it must return an error 42 (Provided authentication mechanism not supported).

In both cases, it is recommended that the server provide a meaningful url (configuration url, documentation, etc) in the helpUrl to help clients instruct their users how to obtain an API key.

New error codes

This extension introduces three new errors 42, 43 and 44, and adds a new field helpUrl. See error

2 - HTTP form POST

OpenSubsonic version: 1

OpenSubsonic extension name formPost (As returned by getOpenSubsonicExtensions)

Version 1

This extension requires that the server support passing API arguments via POST with the arguments respecting the application/x-www-form-urlencoded format.

See: API reference

3 - Song Lyrics

OpenSubsonic version: 1

OpenSubsonic extension name songLyrics (As returned by getOpenSubsonicExtensions)

Version 1

This extension requires the following endpoints:

• getLyricsBySongId: Fetch structured song lyrics by id

4 - Template extension

OpenSubsonic version: 1

OpenSubsonic extension name: template (As returned by getOpenSubsonicExtensions)

This is a template extension that allows servers to do marvelous stuff and clients to use that stuff.

Version 1

You can now bake cakes and brownies via the API!

This extension requires the following endpoints:

• bakeCake To bake cakes.
• bakeBrownie To bake brownies.

Version 2

You can now bake a lot of stuff via the API!

This extension requires the following endpoints:

• bakeSomething To bake something.

5 - Transcode Offset

OpenSubsonic version: 1

OpenSubsonic extension name: transcodeOffset (As returned by getOpenSubsonicExtensions)

When a server support this extension this means that it support the timeOffset parameter of the stream endpoint for music.

Version 1

You can now start transcoding at any position in the media, allowing seeking when transcoding on the clients!

This extension requires the support of the timeOffset parameter of the stream endpoint for music.