Merge branch 'master' of github.com:krateng/maloja

API.md

@@ -20,7 +20,32 @@ Server URL | Your Maloja URL followed by `/apis/audioscrobbler_legacy`
 Username | Doesn't matter
 Password | Any of your API keys
 
-Note that this is the base URL - some scrobblers ask you for the full endpoint instead.
+| :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
 
@@ -32,6 +57,7 @@ No application should ever rely on the non-existence of fields in the JSON data
 
 ## General Structure
 
+  
 Most endpoints follow this structure:
 
 | Key | Type | Description |
@@ -40,10 +66,11 @@ Most endpoints follow this structure:
 | `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 |
@@ -64,7 +91,10 @@ Whenever a list of entities is returned, they have the following fields:
 | `duration` | Integer | How long the track was played for in seconds |
 | `origin` | String | Client that submitted the scrobble, or import source |
 
-**Example**
+
+<table>
+  <tr><td>:memo: Example </td><tr>
+  <tr><td>
    
 ```json
 {
@@ -79,6 +109,11 @@ Whenever a list of entities is returned, they have the following fields:
 }
 ```
     
+  </tr></td>
+</table>
+  
+
+
 ### Track
 
 | Key | Type | Description |
@@ -87,7 +122,9 @@ Whenever a list of entities is returned, they have the following fields:
 | `title` | String | The title of the track |
 | `length` | Integer | The full length of the track in seconds |
 
-**Example**
+<table>
+  <tr><td>:memo: Example </td><tr>
+  <tr><td>
    
 ```json
 {
@@ -97,12 +134,24 @@ Whenever a list of entities is returned, they have the following fields:
 }
 ```
     
+  </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>

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