mirror of
https://github.com/rembo10/headphones.git
synced 2026-03-17 10:19:25 +00:00
Updated the basic repository files. Structured API documentation, added CONTRIBUTING.md
This commit is contained in:
Bas Stottelaar
109
API.md
Normal file
109
API.md
Normal file
@@ -0,0 +1,109 @@
|
||||
# API Reference
|
||||
The API is still pretty new and needs some serious cleaning up on the backend but should be reasonably functional. There are no error codes yet.
|
||||
|
||||
## General structure
|
||||
The API endpoint is `http://ip:port + HTTP_ROOT + /api?apikey=$apikey&cmd=$command`
|
||||
|
||||
Data response in JSON formatted. If executing a command like "delArtist" or "addArtist" you'll get back an "OK", else, you'll get the data you requested.
|
||||
|
||||
## API methods
|
||||
|
||||
### getIndex
|
||||
Fetch data from index page. Returns: ArtistName, ArtistSortName, ArtistID, Status, DateAdded, [LatestAlbum, ReleaseDate, AlbumID], HaveTracks, TotalTracks, IncludeExtras, LastUpdated, [ArtworkURL, ThumbURL]: a remote url to the artwork/thumbnail.
|
||||
|
||||
To get the cached image path, see getArtistArt command. ThumbURL is added/updated when an artist is added/updated. If your using the database method to get the artwork, it's more reliable to use the ThumbURL than the ArtworkURL)
|
||||
|
||||
### getArtist&id=$artistid
|
||||
Fetch artist data. returns the artist object (see above) and album info: Status, AlbumASIN, DateAdded, AlbumTitle, ArtistName, ReleaseDate, AlbumID, ArtistID, Type, ArtworkURL: hosted image path. For cached image, see getAlbumArt command)
|
||||
|
||||
### getAlbum&id=$albumid
|
||||
Fetch data from album page. Returns the album object, a description object and a tracks object. Tracks contain: AlbumASIN, AlbumTitle, TrackID, Format, TrackDuration (ms), ArtistName, TrackTitle, AlbumID, ArtistID, Location, TrackNumber, CleanName (stripped of punctuation /styling), BitRate)
|
||||
|
||||
### getUpcoming
|
||||
Returns: Status, AlbumASIN, DateAdded, AlbumTitle, ArtistName, ReleaseDate, AlbumID, ArtistID, Type
|
||||
|
||||
### getWanted
|
||||
Returns: Status, AlbumASIN, DateAdded, AlbumTitle, ArtistName, ReleaseDate, AlbumID, ArtistID, Type
|
||||
|
||||
### getSimilar
|
||||
Returns similar artists - with a higher "Count" being more likely to be similar. Returns: Count, ArtistName, ArtistID
|
||||
|
||||
### getHistory
|
||||
Returns: Status, DateAdded, Title, URL (nzb), FolderName, AlbumID, Size (bytes)
|
||||
|
||||
### getLogs
|
||||
Not working yet
|
||||
|
||||
### findArtist&name=$artistname[&limit=$limit]
|
||||
Perform artist query on musicbrainz. Returns: url, score, name, uniquename (contains disambiguation info), id)
|
||||
|
||||
### findAlbum&name=$albumname[&limit=$limit]
|
||||
Perform album query on musicbrainz. Returns: title, url (artist), id (artist), albumurl, albumid, score, uniquename (artist - with disambiguation)
|
||||
|
||||
### addArtist&id=$artistid
|
||||
Add an artist to the db by artistid)
|
||||
|
||||
### addAlbum&id=$releaseid
|
||||
Add an album to the db by album release id
|
||||
|
||||
### delArtist&id=$artistid
|
||||
Delete artist from db by artistid)
|
||||
|
||||
### pauseArtist&id=$artistid
|
||||
Pause an artist in db)
|
||||
|
||||
### resumeArtist&id=$artistid
|
||||
Resume an artist in db)
|
||||
|
||||
### refreshArtist&id=$artistid
|
||||
Refresh info for artist in db from musicbrainz
|
||||
|
||||
### queueAlbum&id=$albumid[&new=True&lossless=True]
|
||||
Mark an album as wanted and start the searcher. Optional paramters: 'new' looks for new versions, 'lossless' looks only for lossless versions
|
||||
|
||||
### unqueueAlbum&id=$albumid
|
||||
Unmark album as wanted / i.e. mark as skipped
|
||||
|
||||
### forceSearch
|
||||
force search for wanted albums - not launched in a separate thread so it may take a bit to complete
|
||||
### forceProcess
|
||||
Force post process albums in download directory - also not launched in a separate thread
|
||||
|
||||
### getVersion
|
||||
Returns some version information: git_path, install_type, current_version, installed_version, commits_behind
|
||||
|
||||
### checkGithub
|
||||
Updates the version information above and returns getVersion data
|
||||
|
||||
### shutdown
|
||||
Shut down headphones
|
||||
|
||||
### restart
|
||||
Restart headphones
|
||||
|
||||
### update
|
||||
Update headphones - you may want to check the install type in get version and not allow this if type==exe
|
||||
|
||||
### getArtistArt&id=$artistid
|
||||
Returns either a relative path to the cached image, or a remote url if the image can't be saved to the cache dir
|
||||
|
||||
getAlbumArt&id=$albumid
|
||||
see above
|
||||
|
||||
### getArtistInfo&id=$artistid
|
||||
Returns Summary and Content, both formatted in html.
|
||||
|
||||
### getAlbumInfo&id=$albumid
|
||||
See above, returns Summary and Content.
|
||||
|
||||
### getArtistThumb&id=$artistid
|
||||
Returns either a relative path to the cached thumbnail artist image, or an http:// address if the cache dir can't be written to.
|
||||
|
||||
### getAlbumThumb&id=$albumid
|
||||
See above.
|
||||
|
||||
### choose_specific_download&id=$albumid
|
||||
Gives you a list of results from searcher.searchforalbum(). Basically runs a normal search, but rather than sorting them and downloading the best result, it dumps the data, which you can then pass on to download_specific_release(). Returns a list of dictionaries with params: title, size, url, provider & kind - all of these values must be passed back to download_specific_release
|
||||
|
||||
### download_specific_release&id=albumid&title=$title&size=$size&url=$url&provider=$provider&kind=$kind
|
||||
Allows you to manually pass a choose_specific_download release back to searcher.send_to_downloader()
|
||||
@@ -1,71 +0,0 @@
|
||||
The API is still pretty new and needs some serious cleaning up on the backend but should be
|
||||
reasonably functional. There are no error codes yet,
|
||||
|
||||
|
||||
General structure:
|
||||
http://localhost:8181 + HTTP_ROOT + /api?apikey=$apikey&cmd=$command
|
||||
|
||||
Data returned in json format. If executing a command like "delArtist" or "addArtist" you'll get back an "OK", else, you'll get the data you requested
|
||||
|
||||
$commands¶meters[&optionalparameters]:
|
||||
|
||||
|
||||
getIndex (fetch data from index page. Returns: ArtistName, ArtistSortName, ArtistID, Status, DateAdded,
|
||||
[LatestAlbum, ReleaseDate, AlbumID], HaveTracks, TotalTracks,
|
||||
IncludeExtras, LastUpdated, [ArtworkURL, ThumbURL]: a remote url to the artwork/thumbnail. To get the cached image path, see getArtistArt command.
|
||||
ThumbURL is added/updated when an artist is added/updated. If your using the database method to get the artwork,
|
||||
it's more reliable to use the ThumbURL than the ArtworkURL)
|
||||
|
||||
getArtist&id=$artistid (fetch artist data. returns the artist object (see above) and album info: Status, AlbumASIN, DateAdded, AlbumTitle, ArtistName, ReleaseDate, AlbumID, ArtistID, Type, ArtworkURL: hosted image path. For cached image, see getAlbumArt command)
|
||||
|
||||
getAlbum&id=$albumid (fetch data from album page. Returns the album object, a description object and a tracks object. Tracks contain: AlbumASIN, AlbumTitle, TrackID, Format, TrackDuration (ms), ArtistName, TrackTitle, AlbumID, ArtistID, Location, TrackNumber, CleanName (stripped of punctuation /styling), BitRate)
|
||||
|
||||
getUpcoming (Returns: Status, AlbumASIN, DateAdded, AlbumTitle, ArtistName, ReleaseDate, AlbumID, ArtistID, Type)
|
||||
|
||||
getWanted (Returns: Status, AlbumASIN, DateAdded, AlbumTitle, ArtistName, ReleaseDate, AlbumID, ArtistID, Type)
|
||||
|
||||
getSimilar (Returns similar artists - with a higher "Count" being more likely to be similar. Returns: Count, ArtistName, ArtistID)
|
||||
|
||||
getHistory (Returns: Status, DateAdded, Title, URL (nzb), FolderName, AlbumID, Size (bytes))
|
||||
|
||||
getLogs (not working yet)
|
||||
|
||||
findArtist&name=$artistname[&limit=$limit] (perform artist query on musicbrainz. Returns: url, score, name, uniquename (contains disambiguation info), id)
|
||||
|
||||
findAlbum&name=$albumname[&limit=$limit] (perform album query on musicbrainz. Returns: title, url (artist), id (artist), albumurl, albumid, score, uniquename (artist - with disambiguation)
|
||||
|
||||
addArtist&id=$artistid (add an artist to the db by artistid)
|
||||
addAlbum&id=$releaseid (add an album to the db by album release id)
|
||||
|
||||
delArtist&id=$artistid (delete artist from db by artistid)
|
||||
|
||||
pauseArtist&id=$artistid (pause an artist in db)
|
||||
resumeArtist&id=$artistid (resume an artist in db)
|
||||
|
||||
refreshArtist&id=$artistid (refresh info for artist in db from musicbrainz)
|
||||
|
||||
queueAlbum&id=$albumid[&new=True&lossless=True] (Mark an album as wanted and start the searcher. Optional paramters: 'new' looks for new versions, 'lossless' looks only for lossless versions)
|
||||
unqueueAlbum&id=$albumid (Unmark album as wanted / i.e. mark as skipped)
|
||||
|
||||
forceSearch (force search for wanted albums - not launched in a separate thread so it may take a bit to complete)
|
||||
forceProcess (force post process albums in download directory - also not launched in a separate thread)
|
||||
|
||||
getVersion (Returns some version information: git_path, install_type, current_version, installed_version, commits_behind
|
||||
checkGithub (updates the version information above and returns getVersion data)
|
||||
|
||||
shutdown (shut down headphones)
|
||||
restart (restart headphones)
|
||||
update (update headphones - you may want to check the install type in get version and not allow this if type==exe)
|
||||
|
||||
getArtistArt&id=$artistid (Returns either a relative path to the cached image, or a remote url if the image can't be saved to the cache dir)
|
||||
getAlbumArt&id=$albumid (see above)
|
||||
|
||||
getArtistInfo&id=$artistid (Returns Summary and Content, both formatted in html)
|
||||
getAlbumInfo&id=$albumid (See above, returns Summary and Content)
|
||||
|
||||
getArtistThumb&id=$artistid (Returns either a relative path to the cached thumbnail artist image, or an http:// address if the cache dir can't be written to)
|
||||
getAlbumThumb&id=$albumid (see above)
|
||||
|
||||
choose_specific_download&id=$albumid (Gives you a list of results from searcher.searchforalbum(). Basically runs a normal search, but rather than sorting them and downloading the best result, it dumps the data, which you can then pass on to download_specific_release(). Returns a list of dictionaries with params: title, size, url, provider & kind - all of these values must be passed back to download_specific_release)
|
||||
|
||||
download_specific_release&id=albumid&title=$title&size=$size&url=$url&provider=$provider&kind=$kind (Allows you to manually pass a choose_specific_download release back to searcher.send_to_downloader())
|
||||
35
CONTRIBUTING.md
Normal file
35
CONTRIBUTING.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Contributing to Headphones
|
||||
|
||||
## For users
|
||||
In case you read this because you are posting an issue, please take a minute and conside the things below. The issue tracker is not a support forum. It is primarily intended to submit bugs, improvements or feature requests. However, we are glad to help you, and make sure the problem is not caused by Headphones, but don't expect step-by-step answers.
|
||||
|
||||
* Use the search function. Chances are that your problem is already discussed.
|
||||
* Visit the [Troubleshooting](../../wiki/TroubleShooting) wiki first.
|
||||
* Use [proper formatting](https://help.github.com/articles/github-flavored-markdown/). Paste your logs in code blocks.
|
||||
* Close your issue if you resolved it.
|
||||
|
||||
## For developers
|
||||
If you think you can contribute code to the Headphones repository, do not hesitate to submit a pull request.
|
||||
|
||||
### Branches
|
||||
All pull requests should be based on the `develop` branch. When you want to develop a new feature, clone the repository with `git clone origin/develop -b FEATURE_NAME`. Use meaningful commit messages.
|
||||
|
||||
### Code compatibility
|
||||
The code should work with Python 2.6 and 2.7. Note that Headphones runs on different platforms, including Network Attached Storage devices such as Synology.
|
||||
|
||||
Re-use existing code. Do not hesitate to add logging in your code. You can the logger module `headphones.logger.*` for this. Web requests are invoked via `headphones.request.*` and derived ones. Use these methods to automatically add proper and meaningful error handling.
|
||||
|
||||
### Code conventions
|
||||
Altough Headphones did not adapt a code convention in the past, we try to follow the [PEP8](http://legacy.python.org/dev/peps/pep-0008/) conventions for future code. A short summary to remind you (copied from http://wiki.ros.org/PyStyleGuide):
|
||||
|
||||
* 4 space indentation
|
||||
* 80 characters per line
|
||||
* `package_name`
|
||||
* `ClassName`
|
||||
* `method_name`
|
||||
* `field_name`
|
||||
* `_private_something`
|
||||
* `self.__really_private_field`
|
||||
* `_global`
|
||||
|
||||
Document your code!
|
||||
13
README.md
13
README.md
@@ -1,17 +1,17 @@
|
||||
#Headphones
|
||||
|
||||
###Support & Discuss
|
||||
## Support & Discuss
|
||||
|
||||
You are free to join the HP support community on IRC where you can ask questions, hang around and discuss anything related to HP.
|
||||
|
||||
1. Use any IRC client and connect to the Freenode server.
|
||||
2. Join #headphones
|
||||
|
||||
###Installation and Notes
|
||||
## Installation and Notes
|
||||
|
||||
[Read our Wiki](../../wiki) on how to install and use HeadPhones properly.
|
||||
[Read our Wiki](../../wiki) on how to install and configure HeadPhones properly.
|
||||
|
||||
[**Troubleshooting** page](../../wiki/TroubleShooting) in the wiki can help you with comon problems.
|
||||
[**Troubleshooting** page](../../wiki/TroubleShooting) in the wiki can help you with common problems.
|
||||
|
||||
**Issues** can be reported on the GitHub issue tracker considering these rules:
|
||||
|
||||
@@ -30,8 +30,7 @@ If you **comply with these rules** you can [post your request/issue](http://gith
|
||||
**Support** the project by implementing new features, solving support tickets and provide bug fixes.
|
||||
If you change something in the code always make a PR to the developer branch instead of the master branch.
|
||||
|
||||
|
||||
###Screenshots
|
||||
## Screenshots
|
||||
|
||||
Homepage (Artist Overview)
|
||||
|
||||
@@ -62,4 +61,4 @@ Album Page with track overview:
|
||||
|
||||
|
||||
|
||||
This is free software under the GPL v3 open source license - so feel free to do with it what you wish.
|
||||
This is free software under the GPL v3 open source license - so feel free to do with it what you wish. A copy of the license is included.
|
||||
|
||||
Reference in New Issue
Block a user