Pular para o conteúdo principal
Versão: 13.x

API Externa

A API externa permite que programas acessem ou acionem as funcionalidades do UMS com uma chamada HTTP.

Como ativar a API Externa

Edite o arquivo UMS.conf e configure uma "api_key" assim:

api_key = senha_secreta

A senha_secreta deve conter um número mínimo de 12 caracteres.

Uso da API

Se a API Externa estiver habilitada, a API estará acessível com uma chamada POST para o endereço /api/COMMAND

Escaneamento das pastas

rescan

IntençãoEscanear novamente a biblioteca de mídia completa
URI/api/folderscanner/rescan
POST BODYNONE
POST BODY example / descriptionEste comando não necessita de conteúdo no BODY
Disponível desde10.4.2

:::Informação Este comando pode ser bem lento para bibliotecas de mídia grandes :::

Exemplo:

curl -w "%{http_code}\n" -H "api-key: senha_secreta" http://localhost:5001/api/folderscanner/rescan

rescanFileOrFolder

IntençãoEscanear novamente uma subárvore parcial do sistema de arquivos.
URI/api/folderscanner/rescanFileOrFolder
POST BODYCAMINHO_PARA_ESCANEAR
POST BODY exemplo / descriçãoexemplo: "/music/pop/Madonna". O caminho deve ser a raiz da pasta ou uma subpasta de um caminho compartilhado.
Disponível desde10.4.2

Exemplo:

curl -d "CAMINHO_PARA_ESCANEAR" -w "%{http_code}\n" -H "api-key: senha_secreta" -X POST http://localhost:5001/api/folderscanner/rescanFileOrFolder

Curtindo Músicas (álbuns e músicas)

like song

A música será marcada como curtida.

IntençãoCurtir uma música identificada por um trackId do musicBrainz
URI<span class="s1">/api/like/likesong</span>
POST BODYmusicBrainz_trackID
POST BODY exemplo / descriçãob8695995-45e9-405d-b4aa-e50e8760fe25
Disponível desde10.20

Exemplo:

curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/likesong

Descurtir uma música

A música será descurtida

IntençãoDescurtir uma música identificada pelo trackId do musicBrainz
URI<span class="s1">/api/like/</span>dislikesong
POST BODYmusicBrainz_trackID
POST BODY exemplo / descriçãob8695995-45e9-405d-b4aa-e50e8760fe25
Disponível desde10.20

Exemplo:

curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/dislikesong

É uma música curtida

Checar se uma música foi curtida.

IntençãoChecar se uma música foi curtida identificada pelo trackId do musicBrainz
URI<span class="s1">/api/like/</span><span class="s1">issongliked</span>
POST BODYmusicBrainz_trackID
POST BODY exemplo / descriçãob8695995-45e9-405d-b4aa-e50e8760fe25
RESPONSE BODYVERDADEIRO ou FALSO
Disponível desde10.20

Exemplo:

curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/issongliked

Esta chamada acrescenta o atributo curtido do álbum identificado pelo release-id do musicBrainz 1e0eee38-a9f6-49bf-84d0-45d0647799af.

Curtir um álbum

Definir o estado de curtido de um álbum para verdadeiro.

IntençãoCurtir um álbum identificado pelo releaseId do musicBrainz
URI<span class="s1">/api/like/</span>likealbum
POST BODYmusicBrainz_releaseID
POST BODY exemplo / descrição1e0eee38-a9f6-49bf-84d0-45d0647799af
Disponível desde10.20

Exemplo:

curl -d "1e0eee38-a9f6-49bf-84d0-45d0647799af" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/likealbum

Descurtir um álbum

Remover o estado de curtido de um álbum.

IntençãoDescurtir uma música identificada pelo releaseId do musicBrainz
URI<span class="s1">/api/like/</span>dislikealbum
POST BODYmusicBrainz_releaseID
POST BODY exemplo / descrição1e0eee38-a9f6-49bf-84d0-45d0647799af
Disponível desde10.20

Exemplo:

curl -d "1e0eee38-a9f6-49bf-84d0-45d0647799af" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/dislikealbum

Esta chamada removeu o atributo curtido do álbum identificado pelo release-id do musicBrainz 1e0eee38-a9f6-49bf-84d0-45d0647799af.

is album liked

Check album like state.

IntentionCheck if album is liked identified by musicBrainz releaseID
URI<span class="s1">/api/like/</span>isalbumliked
POST BODYmusicBrainz_releaseID
POST BODY example / description1e0eee38-a9f6-49bf-84d0-45d0647799af
RESPONSE BODY"TRUE" or "FALSE"
Available since10.20

Example:

curl -d "1e0eee38-a9f6-49bf-84d0-45d0647799af" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/isalbumliked

This call checks if the album identified by musicbrainz release-id 1e0eee38-a9f6-49bf-84d0-45d0647799af is liked.

Rating

The rating API is responsible for rating songs. Rating information is saved in the internal database (cache enabled) and optionally in the file itself. If audio_update_rating_tag = true is set in UMS.conf the IDv3 rating field also being updated in the song file (if the songs file format is supported).

While browsing the content directory server, MusicBrainzTrackID (if available) and audiotrackID are delivered as desc metadata within the DIDL element.

set rating

IntentionSet rating in stars (0 - 5) on a song identified by musicBrainz trackId
URI<span class="s1">/api/</span><span class="s1">rating/setrating</span>
POST BODYmusicbrainzTrackId /stars
POST BODY example / descriptionb8695995-45e9-405d-b4aa-e50e8760fe25/3
Available since10.20

Example:

curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25/3" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/rating/setrating

This call sets the user rating of all songs identified by the musicbrainz track-id b8695995-45e9-405d-b4aa-e50e8760fe25 to 3.

get rating

Reads song rating from database

IntentionGet song rating in stars (0 - 5) by musicBrainz trackID. Response body contains the rating information.
URI<span class="s1">/api/</span><span class="s1">rating/getrating </span>
POST BODYmusicbrainzTrackId
POST BODY example / descriptionb8695995-45e9-405d-b4aa-e50e8760fe25
RESPONSE BODY example3
Available since10.20

Example:

curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/rating/getrating

This call reads the user rating of a song identified by the musicbrainz track-id b8695995-45e9-405d-b4aa-e50e8760fe25.

set rating by audiotrack id

IntentionSet rating in stars (0 - 5) on a song identified by UMS internal audiotrackID
URI<span class="s1">/api/</span><span class="s1">rating/setRatingByAudiotrackId </span>
POST BODYtrackID /stars
POST BODY example / description32
Available since11.0

Example:

curl -d "32/3" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/rating/setrating

This call sets songs user rating identified by audiotrack id 32 to 3.

get rating by audiotrack id

Reads song rating from database

IntentionGet song rating in stars (0 - 5) by UMS internal audiotrackID. Response body contains the rating information.
URI<span class="s1">/api/</span><span class="s1">rating/getRatingByAudiotrackId</span>
POST BODYtrackId
POST BODY example / description32
RESPONSE BODY example3
Available since11.0

Example:

curl -d "32" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/rating/getRatingByAudiotrackId

This call reads the user rating of a song identified by UMS audiotrack-id 32.

Backup / Restore

User managed "liked album" entries can be backed up into a profile-directory subfolder named database_backup. The filename is MUSIC_BRAINZ_RELEASE_LIKE. In case UMS database gets deleted, just call restore.

backup liked albums

Backup table MUSIC_BRAINZ_RELEASE_LIKE to filesystem

Intentionbackup liked songs to filesystem
URI<span class="s1"><span class="s1">/api/like/</span></span>backupLikedAlbums
REQUEST TYPEGET
RESPONSE BODYOK or error message
Available since10.20

Example:

curl -w "%{http_code}\n" -H "api-key: secret_password" -X GET http://localhost:5001/api/like/backupLikedAlbums

This call will create a backup file containing liked albums.

restore liked albums

Restores table MUSIC_BRAINZ_RELEASE_LIKE from filesystem

Intentionrestore liked songs from backup file
URI<span class="s1"><span class="s1"><span class="s1">/api/like/</span></span></span>restoreLikedAlbums
REQUEST TYPEGET
RESPONSE BODYOK or error message
Available since10.20

Example:

curl -w "%{http_code}\n" -H "api-key: secret_password" -X GET http://localhost:5001/api/like/restoreLikedAlbums

This call restores the backup file.

Playlist

enable service

Edit UMS.conf and configure a managed playlist folder by setting 

<span class="s1">managed_playlist_folder</span> = PATH_TO_PLAYLIST_FOLDER

for enabling this service. By default this service is disabled. The playlist folder path should be located beneath a configured shared <span class="s1">folders</span> path for playlist changed made by this API to be visible by UMS.

list all playlists

Read available playlists. These playlist names have to be used for subsequent calls to add or remove songs.

IntentionDelivers all supported (m3u, m3u8 and pls) and available playlists from configured folder. Besides playlist name, the playlists playlistId is
URI<span class="s1">/api/</span><span class="s1">playlist</span><span class="s1">/</span><span class="s1">getAllPlaylists</span>
REQUEST TYPEGET
RESPONSE BODYJSON array of playlist names
RESPONSE BODY example<span class="s1">["Pop","Jazz","Classic"]</span>
Available since11.0

Example:

curl -d "" -w "\n%{http_code}\n" -H "api-key: secret_password" -X GET http://localhost:5001/api/playlist/getAllPlaylists

Esta chamada listará todas as listas de reprodução disponíveis.

list server accessible playlists

These are all playlist known to UMS (database/cache enabled). These playlist names have to be used for subsequent calls to add or remove songs. The playlist ID can be used to navigate directly to the playlist by browsing the objectId $DBID$PLAYLIST$ concat databaseId.

IntentionDelivers all supported (m3u, m3u8 and pls) and available playlists from configured folder
URI<span class="s1">`/api/</span><span class="s1">playlist</span><span class="s1">/</span>getserverplaylists` ``
REQUEST TYPEGET
RESPONSE BODYJSON array of playlist names
RESPONSE BODY example``
Available sincedev branch

Example:

curl -d "" -w "\n%{http_code}\n" -H "api-key: secret_password" -X GET http://localhost:5001/api/playlist/getserverplaylists

This call will list list all available playlist accessible by UMS.

adding songs to playlists

The required audiotrackid is delivered during UPnP browse requests and can be extracted from the DIDL response attribute descMetadata

<ums-tags>
[...]
    <audiotrackid>ID</audiotrackid>
[...]
</ums-tags>
    <audiotrackid>ID</audiotrackid>
[...]
</ums-tags>
IntentionAdd song to playlist
URI<span class="s1">/api/</span><span class="s1">playlist</span><span class="s1">/</span><span class="s1">addSongToPlaylist</span>
REQUEST TYPEPOST
POST BODYaudiotrackid<span style="background-color: #bfe6ff; font-size: 11.76px; white-space: pre-wrap;">/PLAYLIST</span>
POST BODY example / description123/Pop
RESPONSE BODYNONE
Available since11.0

Example:

curl -d "123/Pop" -w "\n%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/playlist/addSongToPlaylist

This adds the song with the ID 123 to the playlist Pop.

removing songs from playlists

The required audiotrackid is delivered during UPnP browse requests and can be extracted from the DIDL response attribute descMetadata

<ums-tags>
[...]
    <audiotrackid>ID</audiotrackid>
[...]
</ums-tags>
    <audiotrackid>ID</audiotrackid>
[...]
</ums-tags>

``

IntentionRemove song from playlist
URI<span class="s1">/api/</span><span class="s1">playlist</span><span class="s1">/</span><span class="s1">removeSongFromPlaylist</span>
REQUEST TYPEPOST
POST BODYaudiotrackid<span style="background-color: #bfe6ff; font-size: 11.76px; white-space: pre-wrap;">/PLAYLIST</span>
POST BODY example / description123/Pop
RESPONSE BODYNONE
Available since11.0

Example:

curl -d "123/Pop" -w "\n%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/playlist/removeSongFromPlaylist

This removes the song with the ID 123 from the playlist Pop.

create new playlists

Playlist name should be provided without any path and without file extensions. 

IntentionCreating new playlists in managed playlist folder
URI<span class="s1">/api/</span><span class="s1">playlist</span><span class="s1">/</span><span class="s1">createPlaylist</span>
REQUEST TYPEPOST
POST BODY<span style="background-color: #bfe6ff; font-size: 11.76px; white-space: pre-wrap;">PLAYLIST_NAME</span>
POST BODY example / descriptionContemporary
RESPONSE BODYNONE
Available since11.0

Example:

curl -d "Contemporary" -w "\n%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/playlist/createPlaylist

This call creates a new playlist file named Contemporary.m3u8 in the managed playlist folder.

Java code example

This code snippet shows how to use the API with okhttp3 library.

import nextcp.dto. Config;
import nextcp.dto. UmsServerApiKey;
import okhttp3. Call;
import okhttp3. MediaType;
import okhttp3. OkHttpClient;
import okhttp3. Request;
import okhttp3. RequestBody;
import okhttp3.

    Response;

[...]

    public String executeCall() throws IOException
    {
        String postBody = "1e0eee38-a9f6-49bf-84d0-45d0647799af";
        String apiKey = "secret_password";
        RequestBody body = RequestBody.create(postBody, MediaType.parse("application/text"));
        String requestUrl = "http://127.0.0.1:5001/api/like/likealbum";
        Request request = new Request. Builder().url(requestUrl).addHeader("api-key", apiKey).post(body).build();
        Call call = okClient.newCall(request);
        Response response = call.execute();
        return response.body().string();
    }

HTTP return codes

| 200 | OK | | 204 | success if no content is supposed to be returned | | 401 | invalid api key | | 404 | requested object cannot be found | | 417 | API request failed | | 503 | external api is not enabled. Set a api_key in UMS.conf with a length of 12 or more character |