{"id":15044734,"url":"https://github.com/calne-ca/subsonic-java-client","last_synced_at":"2025-04-10T00:42:48.583Z","repository":{"id":53051635,"uuid":"312117264","full_name":"calne-ca/subsonic-java-client","owner":"calne-ca","description":"A Java Client for the Subsonic API","archived":false,"fork":false,"pushed_at":"2024-11-23T02:49:40.000Z","size":247,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-10T00:42:42.249Z","etag":null,"topics":["airsonic","api-client","audio-streaming","home-media","java","java-client","java17","libresonic","music","subsonic","subsonic-client","subsonic-library"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/calne-ca.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-11T23:38:52.000Z","updated_at":"2024-11-23T02:48:02.000Z","dependencies_parsed_at":"2024-08-22T21:46:57.952Z","dependency_job_id":"0dd5a505-a55d-4b9b-a024-19349426f614","html_url":"https://github.com/calne-ca/subsonic-java-client","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calne-ca%2Fsubsonic-java-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calne-ca%2Fsubsonic-java-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calne-ca%2Fsubsonic-java-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calne-ca%2Fsubsonic-java-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/calne-ca","download_url":"https://codeload.github.com/calne-ca/subsonic-java-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137998,"owners_count":21053775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["airsonic","api-client","audio-streaming","home-media","java","java-client","java17","libresonic","music","subsonic","subsonic-client","subsonic-library"],"created_at":"2024-09-24T20:50:58.063Z","updated_at":"2025-04-10T00:42:48.559Z","avatar_url":"https://github.com/calne-ca.png","language":"Java","readme":"# Subsonic Java Client\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/net.beardbot/subsonic-client/badge.svg)](https://search.maven.org/artifact/net.beardbot/subsonic-client) [![Build](https://github.com/calne-ca/subsonic-java-client/workflows/Build/badge.svg)](https://github.com/calne-ca/subsonic-java-client/actions?query=workflow%3ABuild) [![Airsonic Integration](https://github.com/calne-ca/subsonic-java-client/workflows/Airsonic%20Integration/badge.svg)](https://github.com/calne-ca/subsonic-java-client/actions?query=workflow%3A%22Airsonic+Integration%22) [![Subsonic Integration](https://github.com/calne-ca/subsonic-java-client/workflows/Subsonic%20Integration/badge.svg)](https://github.com/calne-ca/subsonic-java-client/actions?query=workflow%3A%22Subsonic+Integration%22) [![codecov](https://codecov.io/gh/calne-ca/subsonic-java-client/branch/master/graph/badge.svg?token=7TSQV4HGAF)](https://codecov.io/gh/calne-ca/subsonic-java-client)\n\nA Java Client for the [Subsonic API](http://www.subsonic.org/pages/api.jsp).\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003enet.beardbot\u003c/groupId\u003e\n    \u003cartifactId\u003esubsonic-client\u003c/artifactId\u003e\n    \u003cversion\u003e0.6.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Compatibility\nThe client is based on the Subsonic API version 1.15.0.\nThe used API version will automatically be adapted to match the server's API version if the server uses an older API version than 1.15.0.\nIn this case only operations supported by the server's API version will work.\nA minimum server API version of 1.13.0 is still required.\n\nThe client is automatically being tested against the latest [airsonic](https://airsonic.github.io/) and [subsonic](http://www.subsonic.org/) servers during its build process.\nIt should work with all servers that implement the Subsonic API.\n\n## Currently Supported Operations\nHere's an overview of which operations this client currently supports.\nNote that depending on the implementation some servers may not support specific operations even it should be supported by the API version of the server.\nFor example airsonic does not support any chat operations while subsonic does.\n\n| API                    | Operation                  | Supported Since |\n|------------------------|----------------------------|-----------------|\n| System                 | **ping**                   | **0.1.0**       |\n|                        | **getLicense**             | **0.1.0**       |\n| Browsing               | **getMusicFolders**        | **0.1.0**       |\n|                        | **getIndexes**             | **0.1.0**       |\n|                        | **getMusicDirectory**      | **0.1.0**       |\n|                        | **getGenres**              | **0.1.0**       |\n|                        | **getArtists**             | **0.1.0**       |\n|                        | **getArtist**              | **0.1.0**       |\n|                        | **getAlbum**               | **0.1.0**       |\n|                        | **getSong**                | **0.1.0**       |\n|                        | getVideos                  | -               |\n|                        | getVideoInfo               | -               |\n|                        | **getArtistInfo**          | **0.5.0**       |\n|                        | **getArtistInfo2**         | **0.5.0**       |\n|                        | **getAlbumInfo**           | **0.5.0**       |\n|                        | **getAlbumInfo2**          | **0.5.0**       |\n|                        | getSimilarSongs            | -               |\n|                        | getSimilarSongs2           | -               |\n|                        | getTopSongs                | -               |\n| Album/song lists       | **getAlbumList**           | **0.5.0**       |\n|                        | **getAlbumList2**          | **0.5.0**       |\n|                        | getRandomSongs             | -               |\n|                        | getSongsByGenre            | -               |\n|                        | **getNowPlaying**          | **0.1.0**       |\n|                        | **getStarred**             | **0.4.0**       |\n|                        | **getStarred2**            | **0.4.0**       |\n| Searching              | search                     | -               |\n|                        | **search2**                | **0.1.0**       |\n|                        | **search3**                | **0.1.0**       |\n| Playlists              | **getPlaylists**           | **0.1.0**       |\n|                        | **getPlaylist**            | **0.1.0**       |\n|                        | **createPlaylist**         | **0.1.0**       |\n|                        | **updatePlaylist**         | **0.1.0**       |\n|                        | **deletePlaylist**         | **0.1.0**       |\n| Media retrieval        | **stream**                 | **0.1.0**       |\n|                        | **download**               | **0.1.0**       |\n|                        | hls                        | -               |\n|                        | getCaptions                | -               |\n|                        | **getCoverArt**            | **0.1.0**       |\n|                        | getLyrics                  | -               |\n|                        | **getAvatar**              | **0.1.0**       |\n| Media annotation       | **star**                   | **0.4.0**       |\n|                        | **unstar**                 | **0.4.0**       |\n|                        | **setRating**              | **0.5.0**       |\n|                        | **scrobble**               | **0.1.0**       |\n| Sharing                | getShares                  | -               |\n|                        | createShare                | -               |\n|                        | updateShare                | -               |\n|                        | deleteShare                | -               |\n| Podcasts               | getPodcasts                | -               |\n|                        | getNewestPodcasts          | -               |\n|                        | refreshPodcasts            | -               |\n|                        | createPodcastChannel       | -               |\n|                        | deletePodcastChannel       | -               |\n|                        | deletePodcastEpisode       | -               |\n|                        | downloadPodcastEpisode     | -               |\n| Jukebox                | jukeboxControl             | -               |\n| Internet radio         | getInternetRadioStations   | -               |\n|                        | createInternetRadioStation | -               |\n|                        | createInternetRadioStation | -               |\n|                        | updateInternetRadioStation | -               |\n|                        | deleteInternetRadioStation | -               |\n| Chat                   | getChatMessages            | -               |\n|                        | addChatMessage             | -               |\n| User management        | **getUser**                | **0.1.0**       |\n|                        | **getUsers**               | **0.1.0**       |\n|                        | **createUser**             | **0.1.0**       |\n|                        | **updateUser**             | **0.1.0**       |\n|                        | **deleteUser**             | **0.1.0**       |\n|                        | **changePassword**         | **0.1.0**       |\n| Bookmarks              | getBookmarks               | -               |\n|                        | createBookmark             | -               |\n|                        | deleteBookmark             | -               |\n|                        | getPlayQueue               | -               |\n|                        | savePlayQueue              | -               |\n| Media library scanning | **getScanStatus**          | **0.1.0**       |\n|                        | **startScan**              | **0.1.0**       |\n\n## Usage\n### Initialization\n```java\nSubsonicPreferences preferences = new SubsonicPreferences(\"http://localhost:13013/airsonic\", \"username\", \"password\");\npreferences.setStreamBitRate(192);\npreferences.setClientName(\"MySubsonicClient\");\n\nSubsonic subsonic = new Subsonic(preferences);\n```\n\n### Test connection\n```java\ntry {\n    if(subsonic.testConnection()){\n        log.info(\"Succesfully connected to server!\")\n    } else {\n        log.error(\"Failed to connect to server!\")\n    }   \n} catch(SubsonicIncompatibilityException e) {\n    log.error(\"The server is not compatible with the client! Please upgrade you server!\")\n}\n```\n\n### Using the API\nEvery Subsonic API group has a corresponding method in the Subsonic class.\nFor example to use the search3 operation from the *Searching* API group you do the following:\n\n```java\nSearchResult3 searchResult = subsonic.searching().search3(\"Caravan Palace\",\n    SearchParams.create().artistCount(0).albumCount(0).songCount(3));\n```\n\nSome API operations have optional parameters.\nTheir values will, in some cases, be directly passed as arguments but usually the method expects a param class.\nThese param classes always have a static *create* method and multiple additional methods representing the parameters.\n\n#### More examples\n```java\n// Scan library and wait until finished\nsubsonic.libraryScan().startScan();\n\nwhile (subsonic.libraryScan().getScanStatus().isScanning()){\n    Thread.sleep(1000);\n}\n```\n\n```java\n// Fetch index and print it\nList\u003cIndex\u003e indexes = subsonic.browsing().getIndexes();\n\nfor (Index index : indexes) {\n    System.out.println(index.getName());\n    for (Artist artist : index.getArtists()) {\n        System.out.println(\"-- \" + artist.getName());\n    }\n}\n```\n\n```java\n// Stream first song from index\nString firstArtistDirectoryId = indexes.get(0).getArtists().get(0).getId();\n\nDirectory directory = subsonic.browsing().getMusicDirectory(firstArtistDirectoryId);\nChild child = directory.getchildren().get(0);\n\nwhile (child.isDir()){\n    directory = subsonic.browsing().getMusicDirectory(child.getId());\n    child = directory.getchildren().get(0);\n}\n\nMediaStream stream = subsonic.media().stream(child.getId());\nsomeAudioPlayer.play(stream.getInputStream());\n```\n\n```java\n// Create a new user with stream and download roles\nsubsonic.users().createUser(\"testUser\", \"password\", \"test@example.com\", \n    CreateUserParams.create().roles(UserRole.STREAM,UserRole.DOWNLOAD));\n```\nEvery other operation supported by this client can be used in a similar way.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcalne-ca%2Fsubsonic-java-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcalne-ca%2Fsubsonic-java-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcalne-ca%2Fsubsonic-java-client/lists"}