mirror of
https://github.com/krateng/maloja.git
synced 2023-08-10 21:12:55 +03:00
Merge branch 'master' into feature-webedit
This commit is contained in:
krateng
commit
74977b18cc
157
API.md
Normal file
157
API.md
Normal file
@ -0,0 +1,157 @@
|
||||
# Scrobbling
|
||||
|
||||
In order to scrobble from a wide selection of clients, you can use Maloja's standard-compliant APIs with the following settings:
|
||||
|
||||
GNU FM |
|
||||
------ | ---------
|
||||
Gnukebox URL | Your Maloja URL followed by `/apis/audioscrobbler`
|
||||
Username | Doesn't matter
|
||||
Password | Any of your API keys
|
||||
|
||||
ListenBrainz |
|
||||
------ | ---------
|
||||
API URL | Your Maloja URL followed by `/apis/listenbrainz`
|
||||
Username | Doesn't matter
|
||||
Auth Token | Any of your API keys
|
||||
|
||||
Audioscrobbler v1.2 |
|
||||
------ | ---------
|
||||
Server URL | Your Maloja URL followed by `/apis/audioscrobbler_legacy`
|
||||
Username | Doesn't matter
|
||||
Password | Any of your API keys
|
||||
|
||||
| :warning: | Note that these are the base URLs - some scrobblers ask you for the full endpoint instead. |
|
||||
|---------------|:------------------------|
|
||||
|
||||
## Scrobbling Guideline
|
||||
|
||||
Maloja makes no assumptions about scrobbling behaviour. The clients should decide when and whether a play is scrobbled - the server will accept it as long as it contains all necessary data. However, a general guideline is:
|
||||
|
||||
* As soon as a track has been played for 50% of its length or 4 minutes, it should be counted as a scrobble
|
||||
* That scrobble should be submitted when the play has ended in order to know its duration
|
||||
* If the total play duration is enough to count as a scrobble, but not longer than the total track length + enough for a second scrobble, it should be submitted as a scrobble with the according duration
|
||||
* If the duration exceeds this value, the first scrobble should be submitted as a scrobble with the duration of the full track length, while the second scrobble is queued up following the above suggestions in regards to remaining time
|
||||
|
||||
|
||||
<table>
|
||||
<tr><td>:memo: Example </td><tr>
|
||||
<tr><td>
|
||||
|
||||
The user starts playing '(Fine Layers of) Slaysenflite', which is exactly 3:00 minutes long.
|
||||
* If the user ends the play after 1:22, no scrobble is submitted
|
||||
* If the user ends the play after 2:06, a scrobble with `"duration":126` is submitted
|
||||
* If the user jumps back several times and ends the play after 3:57, a scrobble with `"duration":237` is submitted
|
||||
* If the user jumps back several times and ends the play after 4:49, two scrobbles with `"duration":180` and `"duration":109` should be submitted
|
||||
|
||||
</td></tr>
|
||||
<table>
|
||||
|
||||
|
||||
# API Documentation
|
||||
|
||||
The native Maloja API is reachable at `/apis/mlj_1`. Endpoints are listed on `/api_explorer`.
|
||||
|
||||
All endpoints return JSON data. POST request can be made with query string or form data arguments, but this is discouraged - JSON should be used whenever possible.
|
||||
|
||||
No application should ever rely on the non-existence of fields in the JSON data - i.e., additional fields can be added at any time without this being considered a breaking change. Existing fields should usually not be removed or changed, but it is always a good idea to add basic handling for missing fields.
|
||||
|
||||
## General Structure
|
||||
|
||||
|
||||
Most endpoints follow this structure:
|
||||
|
||||
| Key | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `status` | String | Status of the request. Can be `success`, `ok`, `error`, `failure`, `no_operation` |
|
||||
| `error` | Mapping | Details about the error if one occured. |
|
||||
| `warnings` | List | Any warnings that did not result in failure, but should be noted. Field is omitted if there are no warnings! |
|
||||
| `desc` | String | Human-readable feedback. This can be shown directly to the user if desired. |
|
||||
| `list` | List | List of returned [entities](#Entity-Structure) |
|
||||
|
||||
|
||||
Both errors and warnings have the following structure:
|
||||
|
||||
| Key | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `type` | String | Name of the error or warning type |
|
||||
| `value` | varies | Specific data for this error or warning instance |
|
||||
| `desc` | String | Human-readable error or warning description. This can be shown directly to the user if desired. |
|
||||
|
||||
|
||||
## Entity Structure
|
||||
|
||||
Whenever a list of entities is returned, they have the following fields:
|
||||
|
||||
### Scrobble
|
||||
|
||||
| Key | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `time` | Integer | Timestamp of the Scrobble in UTC |
|
||||
| `track` | Mapping | The [track](#Track) being scrobbled |
|
||||
| `duration` | Integer | How long the track was played for in seconds |
|
||||
| `origin` | String | Client that submitted the scrobble, or import source |
|
||||
|
||||
|
||||
<table>
|
||||
<tr><td>:memo: Example </td><tr>
|
||||
<tr><td>
|
||||
|
||||
```json
|
||||
{
|
||||
"time": 1650684324,
|
||||
"track": {
|
||||
"artists": ["Jennie Kim","HyunA","LE","SunMi"],
|
||||
"title": "Wow Thing",
|
||||
"length":200
|
||||
},
|
||||
"duration": 196,
|
||||
"origin": "client:navidrome_desktop"
|
||||
}
|
||||
```
|
||||
|
||||
</tr></td>
|
||||
</table>
|
||||
|
||||
|
||||
|
||||
### Track
|
||||
|
||||
| Key | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `artists` | List | The [artists](#Artist) credited with the track |
|
||||
| `title` | String | The title of the track |
|
||||
| `length` | Integer | The full length of the track in seconds |
|
||||
|
||||
<table>
|
||||
<tr><td>:memo: Example </td><tr>
|
||||
<tr><td>
|
||||
|
||||
```json
|
||||
{
|
||||
"artists": ["Blackpink","Chou Tzuyu"],
|
||||
"title": "MORE",
|
||||
"length": 171
|
||||
}
|
||||
```
|
||||
|
||||
</tr></td>
|
||||
</table>
|
||||
|
||||
|
||||
|
||||
### Artist
|
||||
|
||||
Artists are just represented as raw Strings.
|
||||
|
||||
**Example**
|
||||
|
||||
<table>
|
||||
<tr><td>:memo: Example </td><tr>
|
||||
<tr><td>
|
||||
|
||||
```json
|
||||
"Red Velvet"
|
||||
```
|
||||
|
||||
</tr></td>
|
||||
</table>
|
||||
61
README.md
61
README.md
@ -141,6 +141,16 @@ If you would like to import your previous scrobbles, use the command `maloja imp
|
||||
* an official [Spotify data export file](https://www.spotify.com/us/account/privacy/)
|
||||
* the export of another Maloja instance
|
||||
|
||||
⚠️ Never import your data while maloja is running. When you need to do import inside docker container start it in shell mode instead and perform import before starting the container as mentioned above.
|
||||
|
||||
```console
|
||||
docker run -it --entrypoint sh -v $PWD/malojadata:/mljdata -e MALOJA_DATA_DIRECTORY=/mljdata krateng/maloja
|
||||
cd /mljdata
|
||||
maloja import my_last_fm_export.csv
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
To backup your data, run `maloja backup`, optional with `--include_images`.
|
||||
|
||||
### Customization
|
||||
@ -156,56 +166,9 @@ To backup your data, run `maloja backup`, optional with `--include_images`.
|
||||
|
||||
You can set up any amount of API keys in the file `apikeys.yml` in your configuration folder (or via the web interface). It is recommended to define a different API key for every scrobbler you use.
|
||||
|
||||
### Native support
|
||||
Some scrobbler clients support Maloja's native API. You can also use any scrobbler that allows you to set a custom Listenbrainz or GNUFM server. See [API.md](API.md) for details.
|
||||
|
||||
These solutions allow you to directly setup scrobbling to your Maloja server:
|
||||
* [Tauon](https://tauonmusicbox.rocks) Desktop Player
|
||||
* [Web Scrobbler](https://github.com/web-scrobbler/web-scrobbler) Browser Extension
|
||||
* [Multi Scrobbler](https://github.com/FoxxMD/multi-scrobbler) Desktop Application
|
||||
* [Cmus-maloja-scrobbler](https://git.sr.ht/~xyank/cmus-maloja-scrobbler) Script
|
||||
* [OngakuKiroku](https://github.com/Atelier-Shiori/OngakuKiroku) Desktop Application (Mac)
|
||||
* [Maloja Scrobbler](https://chrome.google.com/webstore/detail/maloja-scrobbler/cfnbifdmgbnaalphodcbandoopgbfeeh) Chromium Extension (also included in the repository) for Plex Web, Spotify, Bandcamp, Soundcloud or Youtube Music
|
||||
|
||||
### Native API
|
||||
|
||||
If you want to implement your own method of scrobbling, it's very simple: You only need one POST request to `/apis/mlj_1/newscrobble` with the keys `artist`, `title` and `key` (and optionally `album`,`duration` (in seconds) and `time`(for cached scrobbles)) - either as form-data or json.
|
||||
|
||||
If you're the maintainer of a music player or server and would like to implement native Maloja scrobbling, feel free to reach out - I'll try my best to help. For Python applications, you can simply use the [`malojalib` package](https://pypi.org/project/maloja-lib/) for a consistent interface even with future updates.
|
||||
|
||||
### Standard-compliant API
|
||||
|
||||
You can use any third-party scrobbler that supports the audioscrobbler (GNUFM) or the ListenBrainz protocol. This is still somewhat experimental, but give it a try with these settings:
|
||||
|
||||
GNU FM |
|
||||
------ | ---------
|
||||
Gnukebox URL | Your Maloja URL followed by `/apis/audioscrobbler`
|
||||
Username | Doesn't matter
|
||||
Password | Any of your API keys
|
||||
|
||||
ListenBrainz |
|
||||
------ | ---------
|
||||
API URL | Your Maloja URL followed by `/apis/listenbrainz`
|
||||
Username | Doesn't matter
|
||||
Auth Token | Any of your API keys
|
||||
|
||||
Audioscrobbler v1.2 |
|
||||
------ | ---------
|
||||
Server URL | Your Maloja URL followed by `/apis/audioscrobbler_legacy`
|
||||
Username | Doesn't matter
|
||||
Password | Any of your API keys
|
||||
|
||||
Known working scrobblers:
|
||||
* [Pano Scrobbler](https://github.com/kawaiiDango/pScrobbler) for Android
|
||||
* [Simple Scrobbler](https://simple-last-fm-scrobbler.github.io) for Android
|
||||
* [Airsonic Advanced](https://github.com/airsonic-advanced/airsonic-advanced) (requires you to supply the full endpoint (`yoururl.tld/apis/listenbrainz/1/submit-listens`))
|
||||
* [Funkwhale](https://dev.funkwhale.audio/funkwhale/funkwhale) (use the legacy API `yoururl.tld/apis/audioscrobbler_legacy`)
|
||||
* [mpdscribble](https://github.com/MusicPlayerDaemon/mpdscribble) (use the legacy API `yoururl.tld/apis/audioscrobbler_legacy`)
|
||||
|
||||
I'm thankful for any feedback whether other scrobblers work!
|
||||
|
||||
|
||||
|
||||
### Manual
|
||||
If you're the maintainer of a music player or server and would like to implement native Maloja scrobbling, feel free to reach out!
|
||||
|
||||
If you can't automatically scrobble your music, you can always do it manually on the `/admin_manual` page of your Maloja server.
|
||||
|
||||
|
||||
@ -496,7 +496,7 @@ def start_db():
|
||||
def db_search(query,type=None):
|
||||
results = []
|
||||
if type=="ARTIST":
|
||||
results = [a for a in sqldb.get_artists() if sqldb.normalize_name(query) in sqldb.normalize_name(a)]
|
||||
results = sqldb.search_artist(query)
|
||||
if type=="TRACK":
|
||||
results = [t for t in sqldb.get_tracks() if sqldb.normalize_name(query) in sqldb.normalize_name(t['title'])]
|
||||
results = sqldb.search_track(query)
|
||||
return results
|
||||
|
||||
@ -844,6 +844,26 @@ def get_scrobble(timestamp, include_internal=False, dbconn=None):
|
||||
scrobble = result[0]
|
||||
return scrobbles_db_to_dict(rows=[scrobble], include_internal=include_internal)[0]
|
||||
|
||||
@cached_wrapper
|
||||
@connection_provider
|
||||
def search_artist(searchterm,dbconn=None):
|
||||
op = DB['artists'].select().where(
|
||||
DB['artists'].c.name_normalized.ilike(normalize_name(f"%{searchterm}%"))
|
||||
)
|
||||
result = dbconn.execute(op).all()
|
||||
|
||||
return [get_artist(row.id,dbconn=dbconn) for row in result]
|
||||
|
||||
@cached_wrapper
|
||||
@connection_provider
|
||||
def search_track(searchterm,dbconn=None):
|
||||
op = DB['tracks'].select().where(
|
||||
DB['tracks'].c.title_normalized.ilike(normalize_name(f"%{searchterm}%"))
|
||||
)
|
||||
result = dbconn.execute(op).all()
|
||||
|
||||
return [get_track(row.id,dbconn=dbconn) for row in result]
|
||||
|
||||
|
||||
##### MAINTENANCE
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user