1--- 2title: "API 5 JSON Methods" 3metaTitle: "API 5 JSON Methods" 4metaDescription: "API documentation" 5--- 6 7Let's go through come calls and examples that you can do for each JSON method. 8 9With the exception of Binary methods, all responses will return a HTTP 200 response. 10 11Also remember that Binary data methods will not return JSON; just the file/data you have requested. 12 13Binary methods will also return: 14 15* HTTP 400 responses for a bad or incomplete request 16* HTTP 404 responses where the requests data was not found 17 18## Auth Methods 19 20Auth methods are used for authenticating or checking the status of your session in an Ampache server 21 22### handshake 23 24This is the function that handles verifying a new handshake Takes a timestamp, auth key, and username. 25 26| Input | Type | Description | Optional | 27|-------------|---------|----------------------------------------------------------|----------| 28| 'auth' | string | $passphrase (Timestamp . Password SHA hash) OR (API Key) | NO | 29| 'user' | string | $username (Required if login/password authentication) | YES | 30| 'timestamp' | integer | UNIXTIME() The timestamp used in seed of password hash | YES | 31| | | (Required if login/password authentication) | | 32| 'version' | string | $version (API Version that the application understands) | YES | 33 34* return object 35 36```JSON 37"auth": "", 38"api": "", 39"session_expire": "", 40"update": "", 41"add": "", 42"clean": "", 43"songs": 0, 44"albums": 0, 45"artists": 0, 46"genres": 0, 47"playlists": 0, 48"users": 0, 49"catalogs": 0, 50"videos": 0, 51"podcasts": 0, 52"podcast_episodes": 0, 53"shares": 0, 54"licenses": 0, 55"live_streams": 0, 56"labels": 0 57``` 58 59* throws object 60 61```JSON 62"error": "" 63``` 64 65[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/handshake.json) 66 67### ping 68 69This can be called without being authenticated, it is useful for determining if what the status of the server is, and what version it is running/compatible with 70 71| Input | Type | Description | Optional | 72|-----------|--------|----------------------------------------------------------------------------|----------| 73| 'auth' | string | (Session ID) returns version information and extends the session if passed | YES | 74| 'version' | string | $version (API Version that the application understands) | YES | 75 76* return object 77 78```JSON 79"session_expire": "", 80"server": "", 81"version": "", 82"compatible": "", 83"auth": "", 84"api": "", 85"update": "", 86"add": "", 87"clean": "", 88"songs": 0, 89"albums": 0, 90"artists": 0, 91"genres": 0, 92"playlists": 0, 93"users": 0, 94"catalogs": 0, 95"videos": 0, 96"podcasts": 0, 97"podcast_episodes": 0, 98"shares": 0, 99"licenses": 0, 100"live_streams": 0, 101"labels": 0 102``` 103 104* throws array 105 106```JSON 107"server": "", 108"version": "", 109"compatible": "" 110``` 111 112[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/ping.json) 113 114### goodbye 115 116Destroy a session using the auth parameter. 117 118| Input | Type | Description | Optional | 119|--------|--------|------------------------------------------------|----------| 120| 'auth' | string | (Session ID) destroys the session if it exists | NO | 121 122* return object 123 124```JSON 125"success": "" 126``` 127 128* throws object 129 130```JSON 131"error": "" 132``` 133 134[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/goodbye.json) 135 136## Non-Data Methods 137 138These methods take no parameters beyond your auth key to return information 139 140### system_update 141 142* **NEW** in 5.0.0-develop 143 144Check Ampache for updates and run the update if there is one. 145 146**ACCESS REQUIRED:** 100 (Admin) 147 148* return object 149 150```JSON 151"success": "" 152``` 153 154* throws object 155 156```JSON 157"error": "" 158``` 159 160[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/system_update.json) 161 162### system_preferences 163 164* **NEW** in 5.0.0-develop 165 166Get your server preferences 167 168**ACCESS REQUIRED:** 100 (Admin) 169 170* return array 171 172```JSON 173"preference": [] 174``` 175 176* throws object 177 178```JSON 179"error": "" 180``` 181 182[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/system_preferences.json) 183 184### users 185 186* **NEW** in 5.0.0-develop 187 188Get ids and usernames for your site 189 190* return array 191 192```JSON 193"user": [] 194``` 195 196* throws object 197 198```JSON 199"error": "" 200``` 201 202[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/users.json) 203 204### user_preferences 205 206* **NEW** in 5.0.0-develop 207 208Get your user preferences 209 210* return array 211 212```JSON 213"preference": [] 214``` 215 216* throws object 217 218```JSON 219"error": "" 220``` 221 222[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/user_preferences.json) 223 224### bookmarks 225 226* **NEW** in 5.0.0-develop 227 228Get information about bookmarked media this user is allowed to manage. 229 230* return array 231 232```JSON 233"bookmark": [] 234``` 235 236* throws object 237 238```JSON 239"error": "" 240``` 241 242[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/bookmarks.json) 243 244## Data Methods 245 246Data methods require additional information and parameters to return information 247 248### get_indexes 249 250This takes a collection of inputs and returns ID + name for the object type 251 252| Input | Type | Description | Optional | 253|---------------|------------|-------------------------------------------------------------------------------|----------| 254| 'type' | string | 'song', 'album', 'artist', 'album_artist', 'playlist', | NO | 255| | | 'podcast', 'podcast_episode', 'live_stream' | | 256| 'filter' | string | Value is Alpha Match for returned results, may be more than one letter/number | YES | 257| 'add' | set_filter | ISO 8601 Date Format (2020-09-16) | YES | 258| | | Find objects with an 'add' date newer than the specified date | | 259| 'update' | set_filter | ISO 8601 Date Format (2020-09-16) | YES | 260| | | Find objects with an 'update' time newer than the specified date | | 261| 'include' | boolean | 0,1 include songs in a playlist or episodes in a podcast | YES | 262| 'offset' | integer | Return results starting from this index position | YES | 263| 'limit' | integer | Maximum number of results to return | YES | 264| 'hide_search' | integer | 0,1, if true do not include searches/smartlists in the result | YES | 265 266* return array 267 268```JSON 269"song": []|"album": []|"artist": []|"playlist": []|"podcast": [] 270 271``` 272 273* throws object 274 275```JSON 276"error": "" 277``` 278 279SONGS [Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/get_indexes%20\(song\).json) 280 281ARTIST [Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/get_indexes%20\(artist\).json) 282 283ALBUM [Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/get_indexes%20\(album\).json) 284 285PLAYLIST [Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/get_indexes%20\(playlist\).json) 286 287### advanced_search 288 289#### Using advanced_search 290 291Perform an advanced search given passed rules. This works in a similar way to the web/UI search pages. 292You can pass multiple rules as well as joins to create in depth search results 293 294Rules must be sent in groups of 3 using an int (starting from 1) to designate which rules are combined. 295Use operator ('and', 'or') to choose whether to join or separate each rule when searching. 296 297Refer to the [Advanced Search](https://ampache.org/api/api-advanced-search) page for details about creating searches. 298 299**NOTE** the rules part can be confusing but essentially you can include as many 'arrays' of rules as you want. 300Just add 1 to the rule value to create a new group of rules. 301 302* Mandatory Rule Values 303 * rule_1 304 * rule_1_operator 305 * rule_1_input 306* Optional (Metadata searches **only**) 307 * rule_1_subtype 308 309| Input | Type | Description | Optional | 310|----------|---------|--------------------------------------------------|----------| 311| operator | string | 'and','or' (whether to match one rule or all) | NO | 312| rule_* | array | [rule_1,rule_1_operator,rule_1_input], | NO | 313| rule_* | array | [rule_2,rule_2_operator,rule_2_input], [etc] | YES | 314| type | string | 'song', 'album', 'artist', 'playlist', | NO | 315| | | 'label', 'user', 'video' | | 316| random | boolean | 0, 1 (random order of results; default to 0) | YES | 317| 'offset' | integer | Return results starting from this index position | YES | 318| 'limit' | integer | Maximum number of results to return | YES | 319 320* return array 321 322```JSON 323"song": []|"album": []|"artist": []|"playlist": []|"label": []|"user": []|"video": [] 324``` 325 326* throws object 327 328```JSON 329"error": "" 330``` 331 332SONG [Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/advanced_search%20\(song\).json) 333 334ARTIST [Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/advanced_search%20\(artist\).json) 335 336ALBUM [Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/advanced_search%20\(album\).json) 337 338### artists 339 340This takes a collection of inputs and returns artist objects. 341 342| Input | Type | Description | Optional | 343|----------------|------------|------------------------------------------------------------------|----------| 344| 'filter' | string | Filter results to match this string | YES | 345| 'exact' | boolean | 0,1 if true filter is exact (=) rather than fuzzy (LIKE) | YES | 346| 'add' | set_filter | ISO 8601 Date Format (2020-09-16) | YES | 347| | | Find objects with an 'add' date newer than the specified date | | 348| 'update' | set_filter | ISO 8601 Date Format (2020-09-16) | YES | 349| | | Find objects with an 'update' time newer than the specified date | | 350| 'include' | string | 'albums', 'songs' and will include the corresponding JSON | YES | 351| 'album_artist' | boolean | 0,1 if true filter for album artists only | YES | 352| 'offset' | integer | Return results starting from this index position | YES | 353| 'limit' | integer | Maximum number of results to return | YES | 354 355* return array 356 357```JSON 358"artist": [] 359``` 360 361* throws object 362 363```JSON 364"error": "" 365``` 366 367[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/artists.json) 368 369### artist 370 371This returns a single artist based on the UID of said artist 372 373| Input | Type | Description | Optional | 374|-----------|--------|-------------------------------------------------------------------------------------|----------| 375| 'filter' | string | UID of Artist, returns artist JSON | NO | 376| 'include' | string | 'albums', 'songs' and will include the corresponding JSON nested in the artist JSON | YES | 377 378* return object 379 380```JSON 381"id": "", 382"name": "", 383"albums": [], 384"albumcount": 0, 385"songs": [], 386"songcount": 0, 387"genre": [], 388"art": "", 389"flag": 0, 390"preciserating": 0, 391"rating": 0, 392"averagerating": 0, 393"mbid": "", 394"summary": "", 395"time": 0, 396"yearformed": 0, 397"placeformed": "" 398``` 399 400* throws object 401 402```JSON 403"error": "" 404``` 405 406[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/artist.json) 407 408### artist_albums 409 410This returns the albums of an artist 411 412| Input | Type | Description | Optional | 413|----------|---------|--------------------------------------------------|----------| 414| 'filter' | string | UID of Artist, returns Album JSON | NO | 415| 'offset' | integer | Return results starting from this index position | YES | 416| 'limit' | integer | Maximum number of results to return | YES | 417 418* return array 419 420```JSON 421album": [] 422``` 423 424* throws object 425 426```JSON 427"error": "" 428``` 429 430[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/artist_albums.json) 431 432### artist_songs 433 434This returns the songs of the specified artist 435 436| Input | Type | Description | Optional | 437|----------|---------|--------------------------------------------------|----------| 438| 'filter' | string | UID of Artist, returns Song JSON | NO | 439| 'top50' | boolean | 0,1, if true filter to the artist top 50 | YES | 440| 'offset' | integer | Return results starting from this index position | YES | 441| 'limit' | integer | Maximum number of results to return | YES | 442 443* return array 444 445```JSON 446"song": [] 447``` 448 449* throws object 450 451```JSON 452"error": "" 453``` 454 455[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/artist_songs.json) 456 457### albums 458 459This returns albums based on the provided search filters 460 461| Input | Type | Description | Optional | 462|-----------|------------|------------------------------------------------------------------|----------| 463| 'filter' | string | Filter results to match this string | YES | 464| 'exact' | boolean | 0,1 if true filter is exact (=) rather than fuzzy (LIKE) | YES | 465| 'add' | set_filter | ISO 8601 Date Format (2020-09-16) | YES | 466| | | Find objects with an 'add' date newer than the specified date | | 467| 'update' | set_filter | ISO 8601 Date Format (2020-09-16) | YES | 468| | | Find objects with an 'update' time newer than the specified date | | 469| 'offset' | integer | Return results starting from this index position | YES | 470| 'limit' | integer | Maximum number of results to return | YES | 471| 'include' | string | 'albums', 'songs' will include nested in the album JSON | YES | 472 473* return array 474 475```JSON 476"album": [] 477``` 478 479* throws object 480 481```JSON 482"error": "" 483``` 484 485[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/albums.json) 486 487### album 488 489This returns a single album based on the UID provided 490 491| Input | Type | Description | Optional | 492|-----------|--------|----------------------------------------------------------------------|----------| 493| 'filter' | string | UID of Album, returns album JSON | NO | 494| 'include' | string | 'songs' will include the corresponding JSON nested in the album JSON | YES | 495 496* return object 497 498```JSON 499"id": "", 500"name": "", 501"artist": {}, 502"time": 0, 503"year": 0, 504"tracks": [], 505"songcount": 0, 506"diskcount": 0, 507"type": "", 508"genre": [], 509"art": "", 510"flag": 0, 511"preciserating": 0.0, 512"rating": 0.0, 513"averagerating": 0.0, 514"mbid": "" 515``` 516 517* throws object 518 519```JSON 520"error": "" 521``` 522 523[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/album.json) 524 525### album_songs 526 527This returns the songs of a specified album 528 529| Input | Type | Description | Optional | 530|----------|---------|----------------------------------------------------|----------| 531| 'filter' | string | UID of Album, returns song JSON | NO | 532| 'exact' | boolean | 0,1 if true don't group songs from different disks | YES | 533| 'offset' | integer | Return results starting from this index position | YES | 534| 'limit' | integer | Maximum number of results to return | YES | 535 536* return array 537 538```JSON 539"song": [] 540``` 541 542* throws object 543 544```JSON 545"error": "" 546``` 547 548[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/album_songs.json) 549 550### genres 551 552This returns the genres (Tags) based on the specified filter 553 554| Input | Type | Description | Optional | 555|----------|---------|----------------------------------------------------------|----------| 556| 'filter' | string | Filter results to match this string | YES | 557| 'exact' | boolean | 0,1 if true filter is exact (=) rather than fuzzy (LIKE) | YES | 558| 'offset' | integer | Return results starting from this index position | YES | 559| 'limit' | integer | Maximum number of results to return | YES | 560 561* return array 562 563```JSON 564"genre": [] 565``` 566 567* throws object 568 569```JSON 570"error": "" 571``` 572 573[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/genres.json) 574 575### genre 576 577This returns a single genre based on UID 578 579| Input | Type | Description | Optional | 580|----------|--------|----------------------------------|----------| 581| 'filter' | string | UID of genre, returns genre JSON | NO | 582 583* return object 584 585```JSON 586"id": "", 587"name": "", 588"albums": 0, 589"artists": 0, 590"songs": 0, 591"videos": 0, 592"playlists": 0, 593"live_streams": 0 594``` 595 596* throws object 597 598```JSON 599"error": "" 600``` 601 602[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/genre.json) 603 604### genre_artists 605 606This returns the artists associated with the genre in question as defined by the UID 607 608| Input | Type | Description | Optional | 609|----------|---------|--------------------------------------------------|----------| 610| 'filter' | string | UID of genre, returns artist JSON | YES | 611| 'offset' | integer | Return results starting from this index position | YES | 612| 'limit' | integer | Maximum number of results to return | YES | 613 614* return array 615 616```JSON 617"artist": [] 618``` 619 620* throws object 621 622```JSON 623"error": "" 624``` 625 626[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/genre_artists.json) 627 628### genre_albums 629 630This returns the albums associated with the genre in question 631 632| Input | Type | Description | Optional | 633|----------|---------|--------------------------------------------------|----------| 634| 'filter' | string | UID of genre, returns album JSON | YES | 635| 'offset' | integer | Return results starting from this index position | YES | 636| 'limit' | integer | Maximum number of results to return | YES | 637 638* return array 639 640```JSON 641"album": [] 642``` 643 644* throws object 645 646```JSON 647"error": "" 648``` 649 650[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/genre_albums.json) 651 652### genre_songs 653 654returns the songs for this genre 655 656| Input | Type | Description | Optional | 657|----------|---------|--------------------------------------------------|----------| 658| 'filter' | string | UID of genre, returns song JSON | YES | 659| 'offset' | integer | Return results starting from this index position | YES | 660| 'limit' | integer | Maximum number of results to return | YES | 661 662* return array 663 664```JSON 665"song": [] 666``` 667 668* throws object 669 670```JSON 671"error": "" 672``` 673 674[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/genre_songs.json) 675 676### songs 677 678Returns songs based on the specified filter 679 680| Input | Type | Description | Optional | 681|----------|------------|------------------------------------------------------------------|----------| 682| 'filter' | string | Filter results to match this string | YES | 683| 'exact' | boolean | 0,1 if true filter is exact (=) rather than fuzzy (LIKE) | YES | 684| 'add' | set_filter | ISO 8601 Date Format (2020-09-16) | YES | 685| | | Find objects with an 'add' date newer than the specified date | | 686| 'update' | set_filter | ISO 8601 Date Format (2020-09-16) | YES | 687| | | Find objects with an 'update' time newer than the specified date | | 688| 'offset' | integer | Return results starting from this index position | YES | 689| 'limit' | integer | Maximum number of results to return | YES | 690 691* return array 692 693```JSON 694"song": [] 695``` 696 697* throws object 698 699```JSON 700"error": "" 701``` 702 703[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/songs.json) 704 705### song 706 707returns a single song 708 709| Input | Type | Description | Optional | 710|----------|--------|--------------------------------|----------| 711| 'filter' | string | UID of Song, returns song JSON | NO | 712 713* return object 714 715```JSON 716"id": "", 717"title": "", 718"name": "", 719"artist": {}, 720"album": {}, 721"genre": [], 722"albumartist": {}, 723"filename": "", 724"track": 0, 725"playlisttrack": 0, 726"time": 0, 727"year": 0, 728"bitrate": 0, 729"rate": 0, 730"mode": "", 731"mime": "", 732"url": "", 733"size": 0, 734"mbid": "0", 735"album_mbid": "", 736"artist_mbid": "", 737"albumartist_mbid": ", 738"art": "", 739"flag": 0, 740"preciserating": 0.0, 741"rating": 0.0, 742"averagerating": 0.0, 743"playcount": 0, 744"catalog": 0, 745"composer": "", 746"channels": null, 747"comment": "", 748"publisher": "", 749"language": "", 750"replaygain_album_gain": 0.000000, 751"replaygain_album_peak": 0.000000, 752"replaygain_track_gain": 0.000000, 753"replaygain_track_peak": 0.000000 754``` 755 756* throws object 757 758```JSON 759"error": "" 760``` 761 762[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/song.json) 763 764### song_delete 765 766* **NEW** in 5.0.0-develop 767 768Delete an existing song. (if you are allowed to) 769 770| Input | Type | Description | Optional | 771|----------|--------|-----------------------|----------| 772| 'filter' | string | UID of song to delete | NO | 773 774* return object 775 776```JSON 777"success": "" 778``` 779 780* throws object 781 782```JSON 783"error": "" 784``` 785 786[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/song_delete.json) 787 788### url_to_song 789 790This takes a url and returns the song object in question 791 792| Input | Type | Description | Optional | 793|-------|--------|----------------------------------------------------------------|----------| 794| 'url' | string | Full Ampache URL from server, translates back into a song JSON | NO | 795 796* return object 797 798```JSON 799"id": "", 800"title": "", 801"name": "", 802"artist": {}, 803"album": {}, 804"genre": [], 805"albumartist": {}, 806"filename": "", 807"track": 0, 808"playlisttrack": 0, 809"time": 0, 810"year": 0, 811"bitrate": 0, 812"rate": 0, 813"mode": "", 814"mime": "", 815"url": "", 816"size": 0, 817"mbid": "", 818"album_mbid": "", 819"artist_mbid": "", 820"albumartist_mbid": "", 821"art": "", 822"flag": 0, 823"preciserating": 0.0, 824"rating": 0.0, 825"averagerating": 0.0, 826"playcount": 0, 827"catalog": 0, 828"composer": "", 829"channels": null, 830"comment": "", 831"publisher": "", 832"language": "", 833"replaygain_album_gain": 0.000000, 834"replaygain_album_peak": 0.000000, 835"replaygain_track_gain": 0.000000, 836"replaygain_track_peak": 0.000000 837``` 838 839* throws object 840 841```JSON 842"error": "" 843``` 844 845[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/url_to_song.json) 846 847### playlists 848 849This returns playlists based on the specified filter 850 851| Input | Type | Description | Optional | 852|---------------|------------|------------------------------------------------------------------|----------| 853| 'filter' | string | Filter results to match this string | YES | 854| 'exact' | boolean | 0,1 if true filter is exact (=) rather than fuzzy (LIKE) | YES | 855| 'add' | set_filter | ISO 8601 Date Format (2020-09-16) | YES | 856| | | Find objects with an 'add' date newer than the specified date | | 857| 'update' | set_filter | ISO 8601 Date Format (2020-09-16) | YES | 858| | | Find objects with an 'update' time newer than the specified date | | 859| 'offset' | integer | Return results starting from this index position | YES | 860| 'limit' | integer | Maximum number of results to return | YES | 861| 'hide_search' | integer | 0,1, if true do not include searches/smartlists in the result | YES | 862 863* return array 864 865```JSON 866"playlist": [] 867``` 868 869* throws object 870 871```JSON 872"error": "" 873``` 874 875[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/playlists.json) 876 877### playlist 878 879This returns a single playlist 880 881| Input | Type | Description | Optional | 882|----------|--------|----------------------------------------|----------| 883| 'filter' | string | UID of playlist, returns playlist JSON | NO | 884 885* return array 886 887```JSON 888"playlist": [] 889``` 890 891* throws object 892 893```JSON 894"error": "" 895``` 896 897[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/playlist.json) 898 899### playlist_songs 900 901This returns the songs for a playlist 902 903| Input | Type | Description | Optional | 904|----------|---------|--------------------------------------------------|----------| 905| 'filter' | string | UID of Playlist, returns song JSON | NO | 906| 'offset' | integer | Return results starting from this index position | YES | 907| 'limit' | integer | Maximum number of results to return | YES | 908 909* return array 910 911```JSON 912"song": [] 913``` 914 915* throws object 916 917```JSON 918"error": "" 919``` 920 921[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/playlist_songs.json) 922 923### playlist_create 924 925This create a new playlist and return it 926 927| Input | Type | Description | Optional | 928|--------|--------|-----------------------------------|----------| 929| 'name' | string | Playlist name | NO | 930| 'type' | string | Playlist type 'public', 'private' | YES | 931 932* return array 933 934```JSON 935"playlist": [] 936``` 937 938* throws object 939 940```JSON 941"error": "" 942``` 943 944[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/playlist_create.json) 945 946### playlist_edit 947 948This modifies name and type of a playlist 949Previously name and type were mandatory while filter wasn't. this has been reversed. 950 951| Input | Type | Description | Optional | 952|----------|--------|-------------------------------------------------------------------|----------| 953| 'filter' | string | UID of Playlist | NO | 954| 'name' | string | Playlist name | YES | 955| 'type' | string | Playlist type 'public', 'private' | YES | 956| 'owner' | string | Change playlist owner to the user id (-1 = System playlist) | YES | 957| 'items' | string | comma-separated song_id's (replaces existing items with a new id) | YES | 958| 'tracks' | string | comma-separated playlisttrack numbers matched to 'items' in order | YES | 959 960* return object 961 962```JSON 963"success": "" 964``` 965 966* throws object 967 968```JSON 969"error": "" 970``` 971 972[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/playlist_edit.json) 973 974### playlist_delete 975 976This deletes a playlist 977 978| Input | Type | Description | Optional | 979|----------|--------|-----------------|----------| 980| 'filter' | string | UID of Playlist | NO | 981 982* return object 983 984```JSON 985"success": "" 986``` 987 988* throws object 989 990```JSON 991"error": "" 992``` 993 994[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/playlist_delete.json) 995 996### playlist_add_song 997 998This adds a song to a playlist. setting check=1 will not add duplicates to the playlist 999 1000| Input | Type | Description | Optional | 1001|----------|---------|-----------------------------------------------------------|----------| 1002| 'filter' | string | UID of Playlist | NO | 1003| 'song' | string | UID of song to add to playlist | NO | 1004| 'check' | boolean | 0, 1 Whether to check and ignore duplicates (default = 0) | YES | 1005 1006* return object 1007 1008```JSON 1009"success": "" 1010``` 1011 1012* throws object 1013 1014```JSON 1015"error": "" 1016``` 1017 1018[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/playlist_add_song.json) 1019 1020### playlist_remove_song 1021 1022This remove a song from a playlist. 1023Previous versions required 'track' instead of 'song'. 1024 1025| Input | Type | Description | Optional | 1026|----------|---------|--------------------------------------|----------| 1027| 'filter' | string | UID of Playlist | NO | 1028| 'song' | string | UID of song to remove from playlist | YES | 1029| 'track' | integer | Track number to remove from playlist | YES | 1030 1031* return object 1032 1033```JSON 1034"success": "" 1035``` 1036 1037* throws object 1038 1039```JSON 1040"error": "" 1041``` 1042 1043[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/playlist_remove_song.json) 1044 1045### playlist_generate 1046 1047Get a list of song JSON, indexes or id's based on some simple search criteria 1048'recent' will search for tracks played after 'Popular Threshold' days 1049'forgotten' will search for tracks played before 'Popular Threshold' days 1050'unplayed' added in 400002 for searching unplayed tracks 1051 1052| Input | Type | Description | Optional | 1053|----------|---------|------------------------------------------------------------------|----------| 1054| 'mode' | string | 'recent', 'forgotten', 'unplayed', 'random' (default = 'random') | YES | 1055| 'filter' | string | string LIKE matched to song title | YES | 1056| 'album' | integer | $album_id | YES | 1057| 'artist' | integer | $artist_id | YES | 1058| 'flag' | boolean | get flagged songs only 0, 1 (default = 0) | YES | 1059| 'format' | string | 'song', 'index','id' (default = 'song') | YES | 1060| 'offset' | integer | Return results starting from this index position | YES | 1061| 'limit' | integer | Maximum number of results to return | YES | 1062 1063* return array 1064 1065```JSON 1066"song": []|"index": []|"id": [] 1067``` 1068 1069* throws object 1070 1071```JSON 1072"error": "" 1073``` 1074 1075SONG [Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/playlist_generate%20\(song\).json) 1076 1077INDEX [Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/playlist_generate%20\(index\).json) 1078 1079ID [Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/playlist_generate%20\(id\).json) 1080 1081### shares 1082 1083This searches the shares and returns... shares 1084 1085| Input | Type | Description | Optional | 1086|----------|---------|--------------------------------------------------|----------| 1087| 'filter' | string | Filter results to match this string | YES | 1088| 'exact' | boolean | 0, 1 boolean to match the exact filter string | YES | 1089| 'offset' | integer | Return results starting from this index position | YES | 1090| 'limit' | integer | Maximum number of results to return | YES | 1091 1092* return array 1093 1094```JSON 1095"share": [] 1096``` 1097 1098* throws object 1099 1100```JSON 1101"error": "" 1102``` 1103 1104[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/shares.json) 1105 1106### share 1107 1108Return shares by UID 1109 1110| Input | Type | Description | Optional | 1111|----------|--------|---------------------------------|----------| 1112| 'filter' | string | UID of Share, returns song JSON | NO | 1113 1114* return object 1115 1116```JSON 1117"id": "", 1118"name": "", 1119"owner": "", 1120"allow_stream": 0, 1121"allow_download": 0, 1122"creation_date": "", 1123"lastvisit_date": "", 1124"object_type": "", 1125"object_id": "", 1126"expire_days": 0, 1127"max_counter": 0, 1128"counter": 0, 1129"secret": "", 1130"public_url": "", 1131"description": "" 1132``` 1133 1134* throws object 1135 1136```JSON 1137"error": "" 1138``` 1139 1140[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/share.json) 1141 1142### share_create 1143 1144Create a public url that can be used by anyone to stream media. 1145Takes the file id with optional description and expires parameters. 1146 1147| Input | Type | Description | Optional | 1148|---------------|---------|-----------------------------------------------|----------| 1149| 'filter' | string | UID of object you are sharing | NO | 1150| 'type' | string | object_type | NO | 1151| 'description' | string | description (will be filled for you if empty) | YES | 1152| 'expires' | integer | days to keep active | YES | 1153 1154* return array 1155 1156```JSON 1157"share": [] 1158``` 1159 1160* throws object 1161 1162```JSON 1163"error": "" 1164``` 1165 1166[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/share_create.json) 1167 1168### share_edit 1169 1170Update the description and/or expiration date for an existing share. 1171Takes the share id to update with optional description and expires parameters. 1172 1173| Input | Type | Description | Optional | 1174|---------------|---------|------------------------------|----------| 1175| 'filter' | string | Alpha-numeric search term | NO | 1176| 'stream' | boolean | 0, 1 | YES | 1177| 'download' | boolean | 0, 1 | YES | 1178| 'expires' | integer | number of days before expiry | YES | 1179| 'description' | string | update description | YES | 1180 1181* return object 1182 1183```JSON 1184"success": "" 1185``` 1186 1187* throws object 1188 1189```JSON 1190"error": "" 1191``` 1192 1193[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/share_edit.json) 1194 1195### share_delete 1196 1197Delete an existing share. 1198 1199| Input | Type | Description | Optional | 1200|----------|--------|------------------------|----------| 1201| 'filter' | string | UID of Share to delete | NO | 1202 1203* return object 1204 1205```JSON 1206"success": "" 1207``` 1208 1209* throws object 1210 1211```JSON 1212"error": "" 1213``` 1214 1215[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/share_delete.json) 1216 1217### get_similar 1218 1219Return similar artist id's or similar song ids compared to the input filter 1220 1221| Input | Type | Description | Optional | 1222|----------|---------|--------------------------------------------------|----------| 1223| 'type' | string | 'song' or 'artist' | NO | 1224| 'filter' | integer | artist id or song id | NO | 1225| 'offset' | integer | Return results starting from this index position | YES | 1226| 'limit' | integer | Maximum number of results to return | YES | 1227 1228* return array 1229 1230```JSON 1231"song": []|"artist": [] 1232 1233``` 1234 1235* throws object 1236 1237```JSON 1238"error": "" 1239``` 1240 1241[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/get_similar.json) 1242 1243### search_songs 1244 1245This searches the songs and returns... songs 1246 1247| Input | Type | Description | Optional | 1248|----------|---------|--------------------------------------------------|----------| 1249| 'filter' | string | Filter results to match this string | NO | 1250| 'offset' | integer | Return results starting from this index position | YES | 1251| 'limit' | integer | Maximum number of results to return | YES | 1252 1253* return array 1254 1255```JSON 1256"song": [] 1257``` 1258 1259* throws object 1260 1261```JSON 1262"error": "" 1263``` 1264 1265[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/search_songs.json) 1266 1267### videos 1268 1269This returns video objects! 1270 1271| Input | Type | Description | Optional | 1272|----------|---------|----------------------------------------------------------|----------| 1273| 'filter' | string | Filter results to match this string | YES | 1274| 'exact' | boolean | 0,1 if true filter is exact (=) rather than fuzzy (LIKE) | YES | 1275| 'offset' | integer | Return results starting from this index position | YES | 1276| 'limit' | integer | Maximum number of results to return | YES | 1277 1278* return array 1279 1280```JSON 1281"video": [] 1282``` 1283 1284* throws object 1285 1286```JSON 1287"error": "" 1288``` 1289 1290[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/videos.json) 1291 1292### video 1293 1294This returns a single video 1295 1296| Input | Type | Description | Optional | 1297|----------|--------|----------------------------------|----------| 1298| 'filter' | string | UID of video, returns video JSON | NO | 1299 1300* return object 1301 1302```JSON 1303"id": "", 1304"title": "", 1305"mime": "", 1306"resolution": "", 1307"size": 0, 1308"genre": [], 1309"url": "" 1310``` 1311 1312* throws object 1313 1314```JSON 1315"error": "" 1316``` 1317 1318[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/video.json) 1319 1320### podcasts 1321 1322Get information about podcasts 1323 1324| Input | Type | Description | Optional | 1325|-----------|---------|-------------------------------------------------------------------------------|----------| 1326| 'filter' | string | Value is Alpha Match for returned results, may be more than one letter/number | YES | 1327| 'offset' | integer | Return results starting from this index position | YES | 1328| 'limit' | integer | Maximum number of results to return | YES | 1329| 'include' | string | 'episodes' (include episodes in the response) | YES | 1330 1331* return array 1332 1333```JSON 1334"podcast": [] 1335``` 1336 1337* throws object 1338 1339```JSON 1340"error": "" 1341``` 1342 1343[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/podcasts.json) 1344 1345### podcast 1346 1347Get the podcast from it's id. 1348 1349| Input | Type | Description | Optional | 1350|-----------|--------|-----------------------------------------------|----------| 1351| 'filter' | string | UID of podcast, returns podcast JSON | NO | 1352| 'include' | string | 'episodes' (include episodes in the response) | YES | 1353 1354* return object 1355 1356```JSON 1357"id": "", 1358"name": "", 1359"description": "", 1360"language": "", 1361"copyright": "", 1362"feed_url": "", 1363"generator": "", 1364"website": "", 1365"build_date": "", 1366"sync_date": "", 1367"public_url": "", 1368"podcast_episode": [] 1369``` 1370 1371* throws object 1372 1373```JSON 1374"error": "" 1375``` 1376 1377[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/podcast.json) 1378 1379### podcast_create 1380 1381Create a podcast that can be used by anyone to stream media. 1382Takes the url and catalog parameters. 1383 1384**ACCESS REQUIRED:** 75 (Catalog Manager) 1385 1386| Input | Type | Description | Optional | 1387|-----------|--------|---------------------|----------| 1388| 'url' | string | rss url for podcast | NO | 1389| 'catalog' | string | podcast catalog | NO | 1390 1391* return array 1392 1393```JSON 1394"podcast": [] 1395``` 1396 1397* throws object 1398 1399```JSON 1400"error": "" 1401``` 1402 1403[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/podcast_create.json) 1404 1405### podcast_edit 1406 1407Update the description and/or expiration date for an existing podcast. 1408Takes the podcast id to update with optional description and expires parameters. 1409 1410**ACCESS REQUIRED:** 50 (Content Manager) 1411 1412| Input | Type | Description | Optional | 1413|---------------|--------|---------------------------|----------| 1414| 'filter' | string | Alpha-numeric search term | NO | 1415| 'feed' | string | feed rss xml url | YES | 1416| 'title' | string | title string | YES | 1417| 'website' | string | source website url | YES | 1418| 'description' | string | | YES | 1419| 'generator' | string | | YES | 1420| 'copyright' | string | | YES | 1421 1422* return object 1423 1424```JSON 1425"success": "" 1426``` 1427 1428* throws object 1429 1430```JSON 1431"error": "" 1432``` 1433 1434[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/podcast_edit.json) 1435 1436### podcast_delete 1437 1438Delete an existing podcast. 1439 1440**ACCESS REQUIRED:** 75 (Catalog Manager) 1441 1442| Input | Type | Description | Optional | 1443|----------|--------|--------------------------|----------| 1444| 'filter' | string | UID of podcast to delete | NO | 1445 1446* return object 1447 1448```JSON 1449"success": "" 1450``` 1451 1452* throws object 1453 1454```JSON 1455"error": "" 1456``` 1457 1458[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/podcast_delete.json) 1459 1460### podcast_episodes 1461 1462This returns the episodes for a podcast 1463 1464| Input | Type | Description | Optional | 1465|----------|---------|--------------------------------------------------|----------| 1466| 'filter' | string | UID of podcast | NO | 1467| 'offset' | integer | Return results starting from this index position | YES | 1468| 'limit' | integer | Maximum number of results to return | YES | 1469 1470* return array 1471 1472```JSON 1473"podcast_episode": [] 1474``` 1475 1476* throws object 1477 1478```JSON 1479"error": "" 1480``` 1481 1482[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/podcast_episodes.json) 1483 1484### podcast_episode 1485 1486Get the podcast_episode from it's id. 1487 1488| Input | Type | Description | Optional | 1489|----------|--------|---------------------------|----------| 1490| 'filter' | string | podcast_episode ID number | NO | 1491 1492* return array 1493 1494```JSON 1495"podcast_episode": [] 1496``` 1497 1498* throws object 1499 1500```JSON 1501"error": "" 1502``` 1503 1504[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/podcast_episode.json) 1505 1506### podcast_episode_delete 1507 1508Delete an existing podcast_episode. 1509 1510| Input | Type | Description | Optional | 1511|----------|--------|----------------------------------|----------| 1512| 'filter' | string | UID of podcast_episode to delete | NO | 1513 1514* return object 1515 1516```JSON 1517"success": "" 1518``` 1519 1520* throws object 1521 1522```JSON 1523"error": "" 1524``` 1525 1526[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/podcast_episode_delete.json) 1527 1528### stats 1529 1530Get some items based on some simple search types and filters. (Random by default) 1531This method **HAD** partial backwards compatibility with older api versions but it has now been removed 1532 1533| Input | Type | Description | Optional | 1534|------------|---------|--------------------------------------------------|----------| 1535| 'type' | string | 'song', 'album', 'artist' | NO | 1536| 'filter' | string | 'newest', 'highest', 'frequent', 'recent', | YES | 1537| | | 'forgotten', 'flagged', 'random' | | 1538| 'user_id' | integer | | YES | 1539| 'username' | string | | YES | 1540| 'offset' | integer | Return results starting from this index position | YES | 1541| 'limit' | integer | Maximum number of results to return | YES | 1542 1543* return array 1544 1545```JSON 1546"song": []|"album": []|"artist": [] 1547``` 1548 1549* throws object 1550 1551```JSON 1552"error": "" 1553``` 1554 1555SONG [Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/stats%20\(song\).json) 1556 1557ARTIST [Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/stats%20\(artist\).json) 1558 1559ALBUM [Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/stats%20\(album\).json) 1560 1561### user 1562 1563This get an user public information 1564 1565| Input | Type | Description | Optional | 1566|------------|--------|-------------------------------------|----------| 1567| 'username' | string | Username of the user to get details | NO | 1568 1569* return array 1570 1571```JSON 1572"user": [] 1573``` 1574 1575* throws object 1576 1577```JSON 1578"error": "" 1579``` 1580 1581[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/user.json) 1582 1583### user_create 1584 1585Create a new user. (Requires the username, password and email.) 1586 1587**ACCESS REQUIRED:** 100 (Admin) 1588 1589| Input | Type | Description | Optional | 1590|------------|---------|----------------------------|----------| 1591| 'username' | string | $username | NO | 1592| 'password' | string | hash('sha256', $password)) | NO | 1593| 'email' | string | 'user@gmail.com' | NO | 1594| 'fullname' | string | | YES | 1595| 'disable' | boolean | 0, 1 | YES | 1596 1597* return object 1598 1599```JSON 1600"success": "" 1601``` 1602 1603* throws object 1604 1605```JSON 1606"error": "" 1607``` 1608 1609[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/user_create.json) 1610 1611### user_update 1612 1613Update an existing user. 1614 1615**ACCESS REQUIRED:** 100 (Admin) 1616 1617| Input | Type | Description | Optional | 1618|--------------|---------|----------------------------|----------| 1619| 'username' | string | $username | NO | 1620| 'password' | string | hash('sha256', $password)) | YES | 1621| 'email' | string | 'user@gmail.com' | YES | 1622| 'fullname' | string | | YES | 1623| 'website' | string | | YES | 1624| 'state' | string | | YES | 1625| 'city' | string | | YES | 1626| 'disable' | boolean | 0, 1 | YES | 1627| 'maxbitrate' | string | | YES | 1628 1629* return object 1630 1631```JSON 1632"success": "" 1633``` 1634 1635* throws object 1636 1637```JSON 1638"error": "" 1639``` 1640 1641[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/user_update.json) 1642 1643### user_delete 1644 1645Delete an existing user. 1646 1647**ACCESS REQUIRED:** 100 (Admin) 1648 1649| Input | Type | Description | Optional | 1650|------------|--------|-------------|----------| 1651| 'username' | string | | NO | 1652 1653* return object 1654 1655```JSON 1656"success": "" 1657``` 1658 1659* throws object 1660 1661```JSON 1662"error": "" 1663``` 1664 1665[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/user_update.json) 1666 1667### licenses 1668 1669This returns licenses based on the specified filter 1670 1671| Input | Type | Description | Optional | 1672|----------|------------|------------------------------------------------------------------|----------| 1673| 'filter' | string | Filter results to match this string | YES | 1674| 'exact' | boolean | 0,1 if true filter is exact (=) rather than fuzzy (LIKE) | YES | 1675| 'add' | set_filter | ISO 8601 Date Format (2020-09-16) | YES | 1676| | | Find objects with an 'add' date newer than the specified date | | 1677| 'update' | set_filter | ISO 8601 Date Format (2020-09-16) | YES | 1678| | | Find objects with an 'update' time newer than the specified date | | 1679| 'offset' | integer | | YES | 1680| 'limit' | integer | | YES | 1681 1682* return array 1683 1684```JSON 1685"license": [] 1686``` 1687 1688* throws object 1689 1690```JSON 1691"error": "" 1692``` 1693 1694[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/licenses.json) 1695 1696### license 1697 1698This returns a single license 1699 1700| Input | Type | Description | Optional | 1701|----------|--------|--------------------------------------|----------| 1702| 'filter' | string | UID of license, returns license JSON | NO | 1703 1704* return object 1705 1706```JSON 1707"id": "", 1708"name": "", 1709"description": "", 1710"external_link": "" 1711``` 1712 1713* throws object 1714 1715```JSON 1716"error": "" 1717``` 1718 1719[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/license.json) 1720 1721### license_songs 1722 1723This returns the songs for a license 1724 1725| Input | Type | Description | Optional | 1726|----------|---------|--------------------------------------------------|----------| 1727| 'filter' | string | UID of license, returns song JSON | NO | 1728| 'offset' | integer | Return results starting from this index position | YES | 1729| 'limit' | integer | Maximum number of results to return | YES | 1730 1731* return array 1732 1733```JSON 1734"song": [] 1735``` 1736 1737* throws object 1738 1739```JSON 1740"error": "" 1741``` 1742 1743[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/license_songs.json) 1744 1745### labels 1746 1747* **NEW** in 5.0.0-develop 1748 1749This returns labels based on the specified filter 1750 1751| Input | Type | Description | Optional | 1752|----------|------------|------------------------------------------------------------------|----------| 1753| 'filter' | string | Filter results to match this string | YES | 1754| 'exact' | boolean | 0,1 if true filter is exact (=) rather than fuzzy (LIKE) | YES | 1755| 'add' | set_filter | ISO 8601 Date Format (2020-09-16) | YES | 1756| | | Find objects with an 'add' date newer than the specified date | | 1757| 'update' | set_filter | ISO 8601 Date Format (2020-09-16) | YES | 1758| | | Find objects with an 'update' time newer than the specified date | | 1759| 'offset' | integer | Return results starting from this index position | YES | 1760| 'limit' | integer | Maximum number of results to return | YES | 1761 1762* return array 1763 1764```JSON 1765"label": [] 1766``` 1767 1768* throws object 1769 1770```JSON 1771"error": "" 1772``` 1773 1774[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/labels.json) 1775 1776### label 1777 1778* **NEW** in 5.0.0-develop 1779 1780This returns a single label 1781 1782| Input | Type | Description | Optional | 1783|----------|--------|----------------------------------|----------| 1784| 'filter' | string | UID of label, returns label JSON | NO | 1785 1786* return object 1787 1788```JSON 1789"id": "", 1790"name": "", 1791"artists": 0, 1792"summary": "", 1793"external_link": "'", 1794"address": "", 1795"category": "", 1796"email": "", 1797"website": "", 1798"user": 0 1799``` 1800 1801* throws object 1802 1803```JSON 1804"error": "" 1805``` 1806 1807[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/label.json) 1808 1809### label_artists 1810 1811* **NEW** in 5.0.0-develop 1812 1813This returns the artists for a label 1814 1815| Input | Type | Description | Optional | 1816|----------|---------|--------------------------------------------------|----------| 1817| 'filter' | string | UID of label, returns artist JSON | NO | 1818| 'offset' | integer | Return results starting from this index position | YES | 1819| 'limit' | integer | Maximum number of results to return | YES | 1820 1821* return array 1822 1823```JSON 1824"artist": [] 1825``` 1826 1827* throws object 1828 1829```JSON 1830"error": "" 1831``` 1832 1833[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/label_artists.json) 1834 1835### followers 1836 1837This gets the followers for the requested username 1838 1839| Input | Type | Description | Optional | 1840|------------|--------|--------------------------------------------|----------| 1841| 'username' | string | Username of the user to get followers list | NO | 1842 1843* return array 1844 1845```JSON 1846"user": [] 1847``` 1848 1849* throws object 1850 1851```JSON 1852"error": "" 1853``` 1854 1855[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/followers.json) 1856 1857### following 1858 1859Get a list of people that this user follows 1860 1861| Input | Type | Description | Optional | 1862|------------|--------|--------------------------------------------|----------| 1863| 'username' | string | Username of the user to get following list | NO | 1864 1865* return array 1866 1867```JSON 1868"user": [] 1869``` 1870 1871* throws object 1872 1873```JSON 1874"error": "" 1875``` 1876 1877[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/following.json) 1878 1879### toggle_follow 1880 1881This follow/unfollow an user 1882 1883| Input | Type | Description | Optional | 1884|------------|--------|-----------------------------------------|----------| 1885| 'username' | string | Username of the user to follow/unfollow | NO | 1886 1887* return object 1888 1889```JSON 1890"success": "" 1891``` 1892 1893* throws object 1894 1895```JSON 1896"error": "" 1897``` 1898 1899[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/toggle_follow.json) 1900 1901### last_shouts 1902 1903This gets the latest posted shouts 1904 1905| Input | Type | Description | Optional | 1906|------------|---------|-------------------------------------|----------| 1907| 'username' | string | Get latest shouts for this username | YES | 1908| 'limit' | integer | Maximum number of results to return | YES | 1909 1910* return array 1911 1912```JSON 1913"shout": [] 1914``` 1915 1916* throws object 1917 1918```JSON 1919"error": "" 1920``` 1921 1922[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/last_shouts.json) 1923 1924### rate 1925 1926This rates a library item 1927 1928| Input | Type | Description | Optional | 1929|----------|---------|-----------------------------------------------|---------:| 1930| 'type' | string | 'song', 'album', 'artist', 'playlist', | NO | 1931| | | 'podcast', 'podcast_episode', 'video' | | 1932| | | 'tvshow', 'tvshow_season' | | 1933| 'id' | integer | library item id | NO | 1934| 'rating' | integer | rating between 0-5 | NO | 1935 1936* return object 1937 1938```JSON 1939"success": "" 1940``` 1941 1942* throws object 1943 1944```JSON 1945"error": "" 1946``` 1947 1948[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/rate.json) 1949 1950### flag 1951 1952This flags a library item as a favorite 1953 1954* Setting flag to true (1) will set the flag 1955* Setting flag to false (0) will remove the flag 1956 1957| Input | Type | Description | Optional | 1958|--------|---------|----------------------------------------|---------:| 1959| 'type' | string | 'song', 'album', 'artist', 'playlist', | NO | 1960| | | 'podcast', 'podcast_episode', 'video' | | 1961| | | 'tvshow', 'tvshow_season' | | 1962| 'id' | integer | $object_id | NO | 1963| 'flag' | boolean | 0, 1 | NO | 1964 1965* return object 1966 1967```JSON 1968"success": "" 1969``` 1970 1971* throws object 1972 1973```JSON 1974"error": "" 1975``` 1976 1977[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/flag.json) 1978 1979### record_play 1980 1981Take a song_id and update the object_count and user_activity table with a play. This allows other sources to record play history to Ampache. 1982 1983If you don't supply a user id (optional) then just fall back to you. 1984 1985**ACCESS REQUIRED:** 100 (Admin) permission to change another user's play history 1986 1987| Input | Type | Description | Optional | 1988|----------|---------|-------------|----------| 1989| 'id' | integer | $object_id | NO | 1990| 'user' | integer | $user_id | YES | 1991| 'client' | string | $agent | YES | 1992| 'date' | integer | UNIXTIME() | YES | 1993 1994* return object 1995 1996```JSON 1997"success": "" 1998``` 1999 2000* throws object 2001 2002```JSON 2003"error": "" 2004``` 2005 2006[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/record_play.json) 2007 2008### scrobble 2009 2010Search for a song using text info and then record a play if found. This allows other sources to record play history to ampache 2011 2012| Input | Type | Description | Optional | 2013|--------------|---------|--------------|----------| 2014| 'song' | string | $song_name | NO | 2015| 'artist' | string | $artist_name | NO | 2016| 'album' | string | $album_name | NO | 2017| 'songmbid' | string | $song_mbid | YES | 2018| 'artistmbid' | string | $artist_mbid | YES | 2019| 'albummbid' | string | $album_mbid | YES | 2020| 'date' | integer | UNIXTIME() | YES | 2021| 'client' | string | $agent | YES | 2022 2023* return object 2024 2025```JSON 2026"success": "" 2027``` 2028 2029* throws object 2030 2031```JSON 2032"error": "" 2033``` 2034 2035[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/scrobble.json) 2036 2037### catalogs 2038 2039This searches the catalogs and returns... catalogs 2040 2041| Input | Type | Description | Optional | 2042|----------|--------|------------------------------------|----------| 2043| 'filter' | string | Catalog type: music, clip, tvshow, | YES | 2044| | | movie, personal_video, podcast | | 2045 2046* return array 2047 2048```JSON 2049"catalog": [] 2050``` 2051 2052* throws object 2053 2054```JSON 2055"error": "" 2056``` 2057 2058[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/catalogs.json) 2059 2060### catalog 2061 2062Return catalog by UID 2063 2064| Input | Type | Description | Optional | 2065|----------|--------|----------------|----------| 2066| 'filter' | string | UID of Catalog | NO | 2067 2068* return object 2069 2070```JSON 2071"id": "", 2072"name": "", 2073"type": "", 2074"gather_types": "", 2075"enabled": 0, 2076"last_add": "", 2077"last_clean": "", 2078"last_update": "", 2079"path": "", 2080"rename_pattern": "", 2081"sort_pattern": "" 2082``` 2083 2084* throws object 2085 2086```JSON 2087"error": "" 2088``` 2089 2090[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/catalog.json) 2091 2092### catalog_action 2093 2094Kick off a catalog update or clean for the selected catalog 2095 2096**ACCESS REQUIRED:** 75 (Catalog Manager) 2097 2098| Input | Type | Description | Optional | 2099|-----------|---------|-----------------------------------|----------| 2100| 'task' | string | 'add_to_catalog', 'clean_catalog' | NO | 2101| 'catalog' | integer | $catalog_id | NO | 2102 2103* return object 2104 2105```JSON 2106"success": "" 2107``` 2108 2109* throws object 2110 2111```JSON 2112"error": "" 2113``` 2114 2115[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/catalog_action%20\(clean_catalog\).json) 2116 2117### catalog_file 2118 2119Perform actions on local catalog files. 2120Single file versions of catalog add, clean, verify and remove (delete) 2121Make sure you remember to urlencode those file names! 2122 2123**ACCESS REQUIRED:** 50 (Content Manager) 2124 2125| Input | Type | Description | Optional | 2126|-----------|---------|--------------------------------------|----------| 2127| 'file' | string | FULL path to local file | NO | 2128| 'task' | string | 'add','clean','verify','remove' | NO | 2129| | | (can include comma-separated values) | NO | 2130| 'catalog' | integer | $catalog_id | NO | 2131 2132* return object 2133 2134```JSON 2135"success": "" 2136``` 2137 2138* throws object 2139 2140```JSON 2141"error": "" 2142``` 2143 2144[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/catalog_file.json) 2145 2146### timeline 2147 2148This get an user timeline 2149 2150| Input | Type | Description | Optional | 2151|------------|---------|---------------------------------------------------|----------| 2152| 'username' | string | Username of the user for whom to get the timeline | NO | 2153| 'limit' | integer | Maximum number of results to return | YES | 2154| 'since' | integer | UNIXTIME() | YES | 2155 2156* return array 2157 2158```JSON 2159"activity": [] 2160``` 2161 2162* throws object 2163 2164```JSON 2165"error": "" 2166``` 2167 2168[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/timeline.json) 2169 2170### friends_timeline 2171 2172This get current user friends timeline 2173 2174| Input | Type | Description | Optional | 2175|---------|---------|-------------------------------------|----------| 2176| 'limit' | integer | Maximum number of results to return | YES | 2177| 'since' | integer | UNIXTIME() | NO | 2178 2179* return array 2180 2181```JSON 2182"activity": [] 2183``` 2184 2185* throws object 2186 2187```JSON 2188"error": "" 2189``` 2190 2191[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/friends_timeline.json) 2192 2193### update_from_tags 2194 2195Update a single album, artist, song from the tag data 2196 2197| Input | Type | Description | Optional | 2198|--------|---------|---------------------------------|----------| 2199| 'type' | string | 'artist', 'album', 'song' | NO | 2200| 'id' | integer | $artist_id, $album_id, $song_id | NO | 2201 2202* return object 2203 2204```JSON 2205"success": "" 2206``` 2207 2208* throws object 2209 2210```JSON 2211"error": "" 2212``` 2213 2214[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/update_from_tags.json) 2215 2216### update_artist_info 2217 2218Update artist information and fetch similar artists from last.fm 2219Make sure lastfm_API_key is set in your configuration file 2220 2221**ACCESS REQUIRED:** 75 (Catalog Manager) 2222 2223| Input | Type | Description | Optional | 2224|-------|---------|-------------|----------| 2225| 'id' | integer | $artist_id | NO | 2226 2227* return object 2228 2229```JSON 2230"success": "" 2231``` 2232 2233* throws object 2234 2235```JSON 2236"error": "" 2237``` 2238 2239[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/update_artist_info.json) 2240 2241### update_art 2242 2243Updates a single album, artist, song running the gather_art process 2244Doesn't overwrite existing art by default. 2245 2246**ACCESS REQUIRED:** 75 (Catalog Manager) 2247 2248| Input | Type | Description | Optional | 2249|-------------|---------|-------------------|----------| 2250| 'id' | integer | $object_id | NO | 2251| 'type' | string | 'song', 'podcast' | NO | 2252| 'overwrite' | boolean | 0, 1 | YES | 2253 2254* return object 2255 2256```JSON 2257"success": "" 2258``` 2259 2260* throws object 2261 2262```JSON 2263"error": "" 2264``` 2265 2266[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/update_art.json) 2267 2268### update_podcast 2269 2270Sync and download new podcast episodes 2271 2272**ACCESS REQUIRED:** 50 (Content Manager) 2273 2274| Input | Type | Description | Optional | 2275|-------|---------|-------------|----------| 2276| 'id' | integer | $object_id | NO | 2277 2278* return object 2279 2280```JSON 2281"success": "" 2282``` 2283 2284* throws object 2285 2286```JSON 2287"error": "" 2288``` 2289 2290[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/update_podcast.json) 2291 2292### user_preference 2293 2294* **NEW** in 5.0.0-develop 2295 2296Get your user preference by name 2297 2298| Input | Type | Description | Optional | 2299|----------|--------|---------------------------------------------------|----------| 2300| 'filter' | string | Preference name e.g ('notify_email', 'ajax_load') | NO | 2301 2302* return array 2303 2304```JSON 2305"preference": [] 2306``` 2307 2308* throws object 2309 2310```JSON 2311"error": "" 2312``` 2313 2314[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/user_preference.json) 2315 2316### system_preference 2317 2318* **NEW** in 5.0.0-develop 2319 2320Get your server preference by name 2321 2322**ACCESS REQUIRED:** 100 (Admin) 2323 2324| Input | Type | Description | Optional | 2325|----------|--------|---------------------------------------------------|----------| 2326| 'filter' | string | Preference name e.g ('notify_email', 'ajax_load') | NO | 2327 2328* return array 2329 2330```JSON 2331"preference": [] 2332``` 2333 2334* throws object 2335 2336```JSON 2337"error": "" 2338``` 2339 2340[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/system_preferences.json) 2341 2342### preference_create 2343 2344* **NEW** in 5.0.0-develop 2345 2346Add a new preference to your server 2347 2348**ACCESS REQUIRED:** 100 (Admin) 2349 2350| Input | Type | Description | Optional | 2351|---------------|---------|---------------------------------------------------------|----------| 2352| 'filter' | string | Preference name e.g ('notify_email', 'ajax_load') | NO | 2353| 'type' | string | 'boolean', 'integer', 'string', 'special' | NO | 2354| 'default' | mixed | string or integer default value | NO | 2355| 'category' | string | 'interface', 'internal', 'options', 'playlist', | NO | 2356| | | 'plugins', 'streaming', 'system' | | 2357| 'description' | string | | YES | 2358| 'subcategory' | string | | YES | 2359| 'level' | integer | access level required to change the value (default 100) | YES | 2360 2361* return object 2362 2363```JSON 2364"success": "" 2365``` 2366 2367* throws object 2368 2369```JSON 2370"error": "" 2371``` 2372 2373[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/preference_create.json) 2374 2375### preference_edit 2376 2377* **NEW** in 5.0.0-develop 2378 2379Edit a preference value and apply to all users if allowed 2380 2381**ACCESS REQUIRED:** 100 (Admin) 2382 2383| Input | Type | Description | Optional | | 2384|----------|---------|---------------------------------------------------|---------------------------|----| 2385| 'filter' | string | Preference name e.g ('notify_email', 'ajax_load') | NO | | 2386| 'value' | mixed | (string | integer) Preference value | NO | 2387| 'all' | boolean | 0, 1 apply to all users | YES | | 2388 2389* return object 2390 2391```JSON 2392"success": "" 2393``` 2394 2395* throws object 2396 2397```JSON 2398"error": "" 2399``` 2400 2401[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/preference_edit.json) 2402 2403### preference_delete 2404 2405* **NEW** in 5.0.0-develop 2406 2407Delete a non-system preference by name 2408 2409**ACCESS REQUIRED:** 100 (Admin) 2410 2411| Input | Type | Description | Optional | 2412|----------|--------|---------------------------------------------------|----------| 2413| 'filter' | string | Preference name e.g ('notify_email', 'ajax_load') | NO | 2414 2415* return object 2416 2417```JSON 2418"success": "" 2419``` 2420 2421* throws object 2422 2423```JSON 2424"error": "" 2425``` 2426 2427[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/preference_delete.json) 2428 2429### get_bookmark 2430 2431* **NEW** in 5.0.0-develop 2432 2433Get the bookmark from it's object_id and object_type. 2434 2435| Input | Type | Description | Optional | 2436|----------|--------|---------------------------------------------------|----------| 2437| 'filter' | string | object_id to find | NO | 2438| 'type' | string | object_type ('song', 'video', 'podcast_episode') | NO | 2439 2440* return array 2441 2442```JSON 2443"bookmark": [] 2444``` 2445 2446* throws object 2447 2448```JSON 2449"error": "" 2450``` 2451 2452[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/get_bookmark.json) 2453 2454### bookmark_create 2455 2456* **NEW** in 5.0.0-develop 2457 2458Create a placeholder for the current media that you can return to later. 2459 2460| Input | Type | Description | Optional | 2461|------------|---------|---------------------------------------------------|----------| 2462| 'filter' | string | object_id to find | NO | 2463| 'type' | string | object_type ('song', 'video', 'podcast_episode') | NO | 2464| 'position' | integer | current track time in seconds | NO | 2465| 'client' | string | Agent string. (Default: 'AmpacheAPI') | YES | 2466| 'date' | integer | update time (Default: UNIXTIME()) | YES | 2467 2468* return array 2469 2470```JSON 2471"bookmark": [] 2472``` 2473 2474* throws object 2475 2476```JSON 2477"error": "" 2478``` 2479 2480[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/bookmark_create.json) 2481 2482### bookmark_edit 2483 2484* **NEW** in 5.0.0-develop 2485 2486Edit a placeholder for the current media that you can return to later. 2487 2488| Input | Type | Description | Optional | 2489|------------|---------|---------------------------------------------------|----------| 2490| 'filter' | string | object_id to find | NO | 2491| 'type' | string | object_type ('song', 'video', 'podcast_episode') | NO | 2492| 'position' | integer | current track time in seconds | NO | 2493| 'client' | string | Agent string. (Default: 'AmpacheAPI') | YES | 2494| 'date' | integer | update time (Default: UNIXTIME()) | YES | 2495 2496* return array 2497 2498```JSON 2499"bookmark": [] 2500``` 2501 2502* throws object 2503 2504```JSON 2505"error": "" 2506``` 2507 2508[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/bookmark_edit.json) 2509 2510### bookmark_delete 2511 2512* **NEW** in 5.0.0-develop 2513 2514Delete an existing bookmark. (if it exists) 2515 2516| Input | Type | Description | Optional | 2517|----------|--------|---------------------------------------------------|----------| 2518| 'filter' | string | object_id to delete | NO | 2519| 'type' | string | object_type ('song', 'video', 'podcast_episode') | NO | 2520| 'client' | string | Agent string. (Default: 'AmpacheAPI') | YES | 2521 2522* return object 2523 2524```JSON 2525"success": "" 2526``` 2527 2528* throws object 2529 2530```JSON 2531"error": "" 2532``` 2533 2534[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/bookmark_delete) 2535 2536### deleted_songs 2537 2538* **NEW** in 5.0.0-develop 2539 2540Returns songs that have been deleted from the server 2541 2542| Input | Type | Description | Optional | 2543|----------|---------|--------------------------------------------------|----------| 2544| 'offset' | integer | Return results starting from this index position | YES | 2545| 'limit' | integer | Maximum number of results to return | YES | 2546 2547* return array 2548 2549```JSON 2550"deleted_song": [] 2551``` 2552 2553* throws object 2554 2555```JSON 2556"error": "" 2557``` 2558 2559[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/deleted_songs.json) 2560 2561### deleted_podcast_episodes 2562 2563* **NEW** in 5.0.0-develop 2564 2565This returns the episodes for a podcast that have been deleted 2566 2567| Input | Type | Description | Optional | 2568|----------|---------|--------------------------------------------------|----------| 2569| 'offset' | integer | Return results starting from this index position | YES | 2570| 'limit' | integer | Maximum number of results to return | YES | 2571 2572* return array 2573 2574```JSON 2575"deleted_podcast_episode": [] 2576``` 2577 2578* throws object 2579 2580```JSON 2581"error": "" 2582``` 2583 2584[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/deleted_podcast_episodes.json) 2585 2586### deleted_videos 2587 2588* **NEW** in 5.0.0-develop 2589 2590This returns video objects that have been deleted 2591 2592| Input | Type | Description | Optional | 2593|----------|---------|--------------------------------------------------|----------| 2594| 'offset' | integer | Return results starting from this index position | YES | 2595| 'limit' | integer | Maximum number of results to return | YES | 2596 2597* return array 2598 2599```JSON 2600"deleted_video": [] 2601``` 2602 2603* throws object 2604 2605```JSON 2606"error": "" 2607``` 2608 2609[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/deleted_videos.json) 2610 2611## Binary Data Methods 2612 2613Binary data methods are used for returning raw data to the user such as a image or stream. 2614 2615### stream 2616 2617Streams a given media file. Takes the file id in parameter with optional max bit rate, file format, time offset, size and estimate content length option. 2618 2619| Input | Type | Description | Optional | 2620|-----------|---------|--------------------------------------------------|----------| 2621| 'id' | integer | $object_id | NO | 2622| 'type' | string | 'song', 'podcast' | NO | 2623| 'bitrate' | integer | max bitrate for transcoding | YES | 2624| 'format' | string | 'mp3', 'ogg', 'raw', etc | YES | 2625| 'offset' | integer | Return results starting from this index position | YES | 2626| 'length' | boolean | 0, 1 | YES | 2627 2628* return file (HTTP 200 OK) 2629* throws (HTTP 400 Bad Request) 2630* throws (HTTP 404 Not Found) 2631 2632### download 2633 2634Downloads a given media file. set format=raw to download the full file 2635 2636| Input | Type | Description | Optional | 2637|----------|---------|---------------------------|----------| 2638| 'id' | integer | $object_id | NO | 2639| 'type' | string | 'song', 'podcast_episode' | NO | 2640| 'format' | string | 'mp3', 'ogg', 'raw', etc | YES | 2641 2642* return file (HTTP 200 OK) 2643* throws (HTTP 400 Bad Request) 2644* throws (HTTP 404 Not Found) 2645 2646### get_art 2647 2648Get an art image. 2649 2650| Input | Type | Description | Optional | 2651|--------|---------|------------------------------------------------------------|----------| 2652| 'id' | integer | $object_id | NO | 2653| 'type' | string | 'song', 'artist', 'album', 'playlist', 'search', 'podcast' | NO | 2654 2655* return image (HTTP 200 OK) 2656* throws (HTTP 400 Bad Request) 2657* throws (HTTP 404 Not Found) 2658 2659## Control Methods 2660 2661### localplay 2662 2663This is for controlling localplay 2664 2665| Input | Type | Description | Optional | 2666|-----------|---------|--------------------------------------------------------------|----------| 2667| 'command' | string | 'next', 'prev', 'stop', 'play', 'pause', 'add', 'volume_up', | NO | 2668| | | 'volume_down', 'volume_mute', 'delete_all', 'skip', 'status' | | 2669| 'oid' | integer | object_id | YES | 2670| 'type' | string | 'Song', 'Video', 'Podcast_Episode', 'Channel', | YES | 2671| | | 'Broadcast', 'Democratic', 'Live_Stream' | | 2672| 'clear' | boolean | 0,1 Clear the current playlist before adding | YES | 2673 2674* return object 2675 2676```JSON 2677"localplay": { "command": {} } 2678``` 2679 2680* throws object 2681 2682```JSON 2683"error": "" 2684``` 2685 2686[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/localplay.json) 2687 2688[Example (status)](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/localplay%20\(status\).json) 2689 2690### democratic 2691 2692This is for controlling democratic play (Songs only) 2693 2694* **Method Descriptions** 2695 * vote: +1 vote for the oid 2696 * devote: -1 vote for the oid 2697 * playlist: Return an array of song items with an additional \<vote>[VOTE COUNT]\</vote> element 2698 * play: Returns the URL for playing democratic play 2699 2700| Input | Type | Description | Optional | 2701|----------|---------|------------------------------|----------| 2702| 'oid' | integer | UID of Song object | NO | 2703| 'method' | string | vote, devote, playlist, play | NO | 2704 2705* return object|array 2706 2707```JSON 2708"url": ""|"method": "","result": false|"song": [] 2709``` 2710 2711* throws object 2712 2713```JSON 2714"error": "" 2715``` 2716 2717[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/democratic%20\(play\).json) 2718 2719[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/democratic%20\(vote\).json) 2720 2721[Example](https://raw.githubusercontent.com/ampache/python3-ampache/master/docs/json-responses/democratic%20\(playlist\).json) 2722