Normalize on 4 spaces instead of tabs. Clean up language and formatting.

1 files changed, 314 insertions, 313 deletions

diff --git a/spec.md b/spec.md
index 5aeab4c..ce7a283 100644
--- a/spec.md
+++ b/spec.md
@@ -22,7 +22,7 @@ All API endpoints that return a value return a JSON object unless otherwise note
 
 The `query` request returns a listing of songs, albums, or artists (as specified by `<object type>`) matching the specified `<search query>`. If the query is omitted, returns all objects in the system.
 
-#### The Query String
+#### The Search Query
 
 Each word of `<search query>` in the request URL is matched as a substring against the artist, album, and title of each song. Prefixes of `artist:`, `album:`, and `title:`, _or of any other metadata attribute_, can be used to match exact strings against the respective metadata keys. `*` can be used as a wildcard when matches are exact. All matches, exact or inexact, are case-insensitive. Posix shell-style quoting and escaping is honored. Example searches:
 
@@ -73,38 +73,38 @@ Other keys may also be included; for example:
 
 * `album`
 * `artist`
-* `length`
+* `length` in seconds as a floating point number
 * `track`
 * `genre`
 * `year`
 
 **`GET /query/songs/hendrix`**
 
-	{
-		"total": 311,
-		"offset": 0,
-		"songs": [
-			{
-				"album": "Jimi Hendrix & The Lonnie Youngblood Band",
-				"mimetype": "audio/mpeg",
-				"artist": "Jimi Hendrix",
-				"track": 1,
-				"title": "Red House",
-				"length": 485.8514285714286,
-				"id": "9e414e259ce6ac962c2d60c68787f6e73d04321d"
-			},
-			{
-				"album": "Jimi Hendrix & The Lonnie Youngblood Band",
-				"mimetype": "audio/mpeg",
-				"artist": "Jimi Hendrix",
-				"track": 2,
-				"title": "Whoa 'eeh",
-				"length": 186.25306122448978,
-				"id": "c96018f7503b16ef5b89d01969c96f4bf304669c"
-			},
-			...
-		]
-	}
+    {
+        "total": 311,
+        "offset": 0,
+        "songs": [
+            {
+                "album": "Jimi Hendrix & The Lonnie Youngblood Band",
+                "mimetype": "audio/mpeg",
+                "artist": "Jimi Hendrix",
+                "track": 1,
+                "title": "Red House",
+                "length": 485.8514285714286,
+                "id": "9e414e259ce6ac962c2d60c68787f6e73d04321d"
+            },
+            {
+                "album": "Jimi Hendrix & The Lonnie Youngblood Band",
+                "mimetype": "audio/mpeg",
+                "artist": "Jimi Hendrix",
+                "track": 2,
+                "title": "Whoa 'eeh",
+                "length": 186.25306122448978,
+                "id": "c96018f7503b16ef5b89d01969c96f4bf304669c"
+            },
+            ...
+        ]
+    }
 
 ##### <a name="artists"></a> Artists: `GET /query/artists/<search query>`
 
@@ -114,111 +114,111 @@ Two `include` terms are available: `songs` and `albums`. When either is used alo
 
 **`GET /query/artists/title:Red+House`**
 
-	{
-		"total": 3,
-		"offset": 0,
-		"artists": [
-			{
-				"artist": "Albert King"
-			},
-			{
-				"artist": "G3"
-			},
-			{
-				"artist": "Jimi Hendrix"
-			}
-		]
-	}
-	
+    {
+        "total": 3,
+        "offset": 0,
+        "artists": [
+            {
+                "artist": "Albert King"
+            },
+            {
+                "artist": "G3"
+            },
+            {
+                "artist": "Jimi Hendrix"
+            }
+        ]
+    }
+    
 
 **`GET /query/artists/title:Red+House?include=albums`**
 
-	{
-		"total": 3,
-		"offset": 0,
-		"artists": [
-			{
-				"artist": "Albert King",
-				"albums": [
-					{
-						"album": "Don't Look Back",
-						"albumart": /* ?? */,
-					}
-				]
-			},
-			{
-				"artist": "G3",
-				"albums": [
-					{
-						"album": "G3 Live in Concert",
-						"albumart": /* ?? */,
-					}
-				]
-			},
-			{
-				"artist": "Jimi Hendrix",
-				"albums": [
-					{
-						"album": "Are You Experienced",
-						"albumart": /* ?? */,
-					}
-				]
-			}
-		]
-	}
+    {
+        "total": 3,
+        "offset": 0,
+        "artists": [
+            {
+                "artist": "Albert King",
+                "albums": [
+                    {
+                        "album": "Don't Look Back",
+                        "albumart": /* ?? */,
+                    }
+                ]
+            },
+            {
+                "artist": "G3",
+                "albums": [
+                    {
+                        "album": "G3 Live in Concert",
+                        "albumart": /* ?? */,
+                    }
+                ]
+            },
+            {
+                "artist": "Jimi Hendrix",
+                "albums": [
+                    {
+                        "album": "Are You Experienced",
+                        "albumart": /* ?? */,
+                    }
+                ]
+            }
+        ]
+    }
 
 **`GET /query/artists/title:Red+House?include=songs`**
 
-	{
-		"total": 3,
-		"offset": 0,
-		"artists": [
-			{
-				"artist": "Albert King",
-				"songs": [
-					{
-						"title": "Red House",
-						"album": "Don't Look Back",
-						"artist": "Albert King",
-						"length" 189.124
-						"mimetype": "audio/mpeg",
-						"id": "9e38b12405b3a73bf8cb49876cd36b93bf9f1a17"
-					}
-				]
-			},
-			...
-		]
-	}
+    {
+        "total": 3,
+        "offset": 0,
+        "artists": [
+            {
+                "artist": "Albert King",
+                "songs": [
+                    {
+                        "title": "Red House",
+                        "album": "Don't Look Back",
+                        "artist": "Albert King",
+                        "length" 189.124
+                        "mimetype": "audio/mpeg",
+                        "id": "9e38b12405b3a73bf8cb49876cd36b93bf9f1a17"
+                    }
+                ]
+            },
+            ...
+        ]
+    }
 
 **`GET /query/artists/title:Red+House?include=songs+albums`**
 
-	{
-		"total": 3,
-		"offset": 0,
-		"artists": [
-			{
-				"artist": "Albert King",
-				"albums": [
-					{
-						"album": "Don't Look Back",
-						"albumart": /* ?? */,
-						"songs": [
-							{
-								"title": "Red House",
-								"album": "Don't Look Back",
-								"artist": "Albert King",
-								"length" 189.124
-								"mimetype": "audio/mpeg",
-								"id": "9e38b12405b3a73bf8cb49876cd36b93bf9f1a17",
-								"track": 3
-							}
-						]
-					}
-				]
-			},
-			...
-		]
-	}
+    {
+        "total": 3,
+        "offset": 0,
+        "artists": [
+            {
+                "artist": "Albert King",
+                "albums": [
+                    {
+                        "album": "Don't Look Back",
+                        "albumart": /* ?? */,
+                        "songs": [
+                            {
+                                "title": "Red House",
+                                "album": "Don't Look Back",
+                                "artist": "Albert King",
+                                "length" 189.124
+                                "mimetype": "audio/mpeg",
+                                "id": "9e38b12405b3a73bf8cb49876cd36b93bf9f1a17",
+                                "track": 3
+                            }
+                        ]
+                    }
+                ]
+            },
+            ...
+        ]
+    }
 
 ##### <a name="albums"></a> Albums: `GET /query/albums/<search query>`
 
@@ -228,115 +228,115 @@ Two `include` terms are available: `songs` and `artists`.
 
 **`GET /query/albums/title:Red+Ho*`**
 
-	{
-		"total": 3,
-		"offset": 0,
-		"albums": [
-			{
-				"album": "Don't Look Back",
-				"albumart": /* ?? */
-			},
-			{
-				"album": "G3 Live in Concert",
-				"albumart": /* ?? */
-			},
-			{
-				"album": "Are You Experienced",
-				"albumart": /* ?? */
-			}
-		]
-	}
-	
+    {
+        "total": 3,
+        "offset": 0,
+        "albums": [
+            {
+                "album": "Don't Look Back",
+                "albumart": /* ?? */
+            },
+            {
+                "album": "G3 Live in Concert",
+                "albumart": /* ?? */
+            },
+            {
+                "album": "Are You Experienced",
+                "albumart": /* ?? */
+            }
+        ]
+    }
+    
 **`GET /query/albums/title:Red+Ho*?include=songs`**
 
-	{
-		"total": 3,
-		"offset": 0,
-		"albums": [
-			{
-				"album": "Don't Look Back",
-				"albumart": /* ?? */,
-				"songs": [
-					{
-								"title": "Red House",
-								"album": "Don't Look Back",
-								"artist": "Albert King",
-								"length" 189.124
-								"mimetype": "audio/mpeg",
-								"id": "9e38b12405b3a73bf8cb49876cd36b93bf9f1a17",
-								"track": 3
-					},
-					{
-								"title": "Red Ho Susie",
-								"album": "Don't Look Back",
-								"artist": "Albert King",
-								"length" 121.432
-								"mimetype": "audio/mpeg",
-								"id": "972a1a11f19934401291cc99117ec614933374ce",
-								"track": 5
-					},
-				]
-			},
-			...
-		]
-	}
+    {
+        "total": 3,
+        "offset": 0,
+        "albums": [
+            {
+                "album": "Don't Look Back",
+                "albumart": /* ?? */,
+                "songs": [
+                    {
+                                "title": "Red House",
+                                "album": "Don't Look Back",
+                                "artist": "Albert King",
+                                "length" 189.124
+                                "mimetype": "audio/mpeg",
+                                "id": "9e38b12405b3a73bf8cb49876cd36b93bf9f1a17",
+                                "track": 3
+                    },
+                    {
+                                "title": "Red Ho Susie",
+                                "album": "Don't Look Back",
+                                "artist": "Albert King",
+                                "length" 121.432
+                                "mimetype": "audio/mpeg",
+                                "id": "972a1a11f19934401291cc99117ec614933374ce",
+                                "track": 5
+                    },
+                ]
+            },
+            ...
+        ]
+    }
 
 **`GET /query/albums/title:Red+Ho*?include=artists`**
 
-	{
-		"total": 3,
-		"offset": 0,
-		"albums": [
-			{
-				"album": "Don't Look Back",
-				"albumart": /* ?? */
-			},
-			{
-				"album": "G3 Live in Concert",
-				"albumart": /* ?? */
-			},
-			{
-				"album": "Are You Experienced",
-				"albumart": /* ?? */
-			}
-		],
-		"artists": [ "Albert King", "G3", "Jimi Hendrix" ]
-	}
+    {
+        "total": 3,
+        "offset": 0,
+        "albums": [
+            {
+                "album": "Don't Look Back",
+                "albumart": /* ?? */
+            },
+            {
+                "album": "G3 Live in Concert",
+                "albumart": /* ?? */
+            },
+            {
+                "album": "Are You Experienced",
+                "albumart": /* ?? */
+            }
+        ],
+        "artists": [ "Albert King", "G3", "Jimi Hendrix" ]
+    }
 
 **`GET /query/albums/title:Red+House?include=songs+artists`**
 
-	{
-		"total": 3,
-		"offset": 0,
-		"albums": [
-			{
-				"album": "Don't Look Back",
-				"albumart": /* ?? */,
-				"songs": [
-					{
-								"title": "Red House",
-								"album": "Don't Look Back",
-								"artist": "Albert King",
-								"length" 189.124
-								"mimetype": "audio/mpeg",
-								"id": "9e38b12405b3a73bf8cb49876cd36b93bf9f1a17",
-								"track": 3
-					},
-					{
-								"title": "Red Ho Susie",
-								"album": "Don't Look Back",
-								"artist": "Albert King",
-								"length" 121.432
-								"mimetype": "audio/mpeg",
-								"id": "972a1a11f19934401291cc99117ec614933374ce",
-								"track": 5
-					},
-				]
-			},
-			...
-		],
-		"artists": [ "Albert King", "G3", "Jimi Hendrix" ]
-	}
+    {
+        "total": 3,
+        "offset": 0,
+        "albums": [
+            {
+                "album": "Don't Look Back",
+                "albumart": /* ?? */,
+                "songs": [
+                    {
+                                "title": "Red House",
+                                "album": "Don't Look Back",
+                                "artist": "Albert King",
+                                "length" 189.124
+                                "mimetype": "audio/mpeg",
+                                "id": "9e38b12405b3a73bf8cb49876cd36b93bf9f1a17",
+                                "track": 3
+                    },
+                    {
+                                "title": "Red Ho Susie",
+                                "album": "Don't Look Back",
+                                "artist": "Albert King",
+                                "length" 121.432
+                                "mimetype": "audio/mpeg",
+                                "id": "972a1a11f19934401291cc99117ec614933374ce",
+                                "track": 5
+                    },
+                ]
+            },
+            ...
+        ],
+        "artists": [ "Albert King", "G3", "Jimi Hendrix" ]
+    }
 
 Note: the `artists` object for the `include` query string is superfluous, and exists only for the sake of completeness.
 
@@ -372,33 +372,33 @@ Takes arbitrary number of form parmeters with the key of `id` and returns a zip
 
 Takes POST form parameters `username` and `password`. Returns whether or not login was successful, an authentication token, and sets an HTTP cookie containing that same authentication token.
 
-	Set-Cookie: token=an9292n239201128ana9a
-	
-	{
-		"loggedin": true,
-		"token": "an9292n239201128ana9a"
-	}
+    Set-Cookie: token=an9292n239201128ana9a
+    
+    {
+        "loggedin": true,
+        "token": "an9292n239201128ana9a"
+    }
 
 #### `GET /login`
 
 Returns whether or not the current user is logged in and valid.
 
-	{
-		"loggedin": true
-	}
+    {
+        "loggedin": true
+    }
 
 
 
 #### `DELETE /login`
 #### `POST /logout`
 
-* [Requires authentication](#authentication), but does not accept cookie-based authentication to protect against CSRF
+[Requires authentication](#authentication), but does not accept cookie-based authentication to protect against CSRF.
 
 Logs out the current user by invalidating the current token. Returns an object indiciating success:
 
-	{
-		"loggedin": false
-	}
+    {
+        "loggedin": false
+    }
 
 ### <a name="admin"></a>Administrative Functionality
 
@@ -406,96 +406,96 @@ The following administrative interfaces are optional, but recommended.
 
 #### `GET /scan`
 
-* [Requires authentication](#authentication) of administrative user, but does not accept cookie-based authentication to protect against CSRF
+[Requires authentication](#authentication) of administrative user, but does not accept cookie-based authentication to protect against CSRF.
 
 Instructs the server to scan the library for changes. Returns streaming text output of current scanning operation, of `Content-Type: text/plain`.
 
 #### `GET /logs/ips`
 
-* [Requires authentication](#authentication) of administrative user
+[Requires authentication](#authentication) of administrative user.
 
 Returns an object containing an array of IP addresses and rDNS host names:
 
-	{
-		"ips": [
-			{
-				"ip": "82.235.163.40",
-				"host": "paris.zx2c4.com"
-			},
-			{
-				"ip": "65.27.203.43",
-				"host": "cpe-65-27-203-43.cinci.res.rr.com"
-			},
-			...
-		]
-	}
+    {
+        "ips": [
+            {
+                "ip": "82.235.163.40",
+                "host": "paris.zx2c4.com"
+            },
+            {
+                "ip": "65.27.203.43",
+                "host": "cpe-65-27-203-43.cinci.res.rr.com"
+            },
+            ...
+        ]
+    }
 
 #### `GET /logs/ips/<ip address>`
 
 
-* [Requires authentication](#authentication) of administrative user
+[Requires authentication](#authentication) of administrative user.
 
 Returns an object containing an array of song downloads and zip downloads, with metadata, as well as the `time` as a UNIX time stamp in microseconds and the downloader's `useragent`. Top level items are sorted in reverse chronological order. Zip files are sorted at the top level by the timestamp of the oldest download. Second level items inside the zip file are sorted in forward chronological order.
 
 ##### `GET /logs/ips/82.235.163.40`
 
-	{
-		"downloads": [
-			{
-				"song": {
-					"album": "The Lord of the Rings: The Return of the King",
-					"title": "The Grey Heavens",
-					"ip": "82.235.163.40",
-					"artist": "Howard Shore",
-					"time": 135852693453491,
-					"useragent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.17 (KHTML, like Gecko) Chrome/24.0.1312.52 Safari/537.17",
-					"id": "3910251a03c93dd40c40156494f0f14db329d78a"
-				}
-			},
-			{
-				"song": {
-					"album": "The Lord of the Rings: The Return of the King",
-					"title": "The Return Of The King",
-					"ip": "82.235.163.40",
-					"artist": "Howard Shore",
-					"time": 135852631953447,
-					"useragent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.17 (KHTML, like Gecko) Chrome/24.0.1312.52 Safari/537.17",
-					"id": "d12f652fb772c82b50f0006d3db45af8063711c2"
-				}
-			},
-			{
-				"zip": [
-					{
-						"album": "Dialogues",
-						"title": "Stern Stuff (with Mike Stern)",
-						"ip": "82.235.163.40",
-						"artist": "Jim Hall",
-						"time": 135796967448742,
-						"useragent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.17 (KHTML, like Gecko) Chrome/24.0.1312.45 Safari/537.17",
-						"id": "06a3d18b3f9b51e55d3c978b0635b1738db99ad0"
-					},
-					{
-						"album": "These Times",
-						"title": "I Know You",
-						"ip": "82.235.163.40",
-						"artist": "Mike Stern",
-						"time": 135796967448919,
-						"useragent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.17 (KHTML, like Gecko) Chrome/24.0.1312.45 Safari/537.17",
-						"id": "1296c212778f8984c16ca9e71a8d9c047ff7b6c8"
-					},
-					{
-						"album": "Big Neighborhood",
-						"title": "Song For Pepper",
-						"ip": "82.235.163.40",
-						"artist": "Mike Stern",
-						"time": 135796967449056,
-						"useragent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.17 (KHTML, like Gecko) Chrome/24.0.1312.45 Safari/537.17",
-						"id": "13ab9d011e41f39e5d71aa34d0d9dc9cecbcb2f5"
-					}
-				]
-			}
-		]
-	}
+    {
+        "downloads": [
+            {
+                "song": {
+                    "album": "The Lord of the Rings: The Return of the King",
+                    "title": "The Grey Heavens",
+                    "ip": "82.235.163.40",
+                    "artist": "Howard Shore",
+                    "time": 135852693453491,
+                    "useragent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.17 (KHTML, like Gecko) Chrome/24.0.1312.52 Safari/537.17",
+                    "id": "3910251a03c93dd40c40156494f0f14db329d78a"
+                }
+            },
+            {
+                "song": {
+                    "album": "The Lord of the Rings: The Return of the King",
+                    "title": "The Return Of The King",
+                    "ip": "82.235.163.40",
+                    "artist": "Howard Shore",
+                    "time": 135852631953447,
+                    "useragent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.17 (KHTML, like Gecko) Chrome/24.0.1312.52 Safari/537.17",
+                    "id": "d12f652fb772c82b50f0006d3db45af8063711c2"
+                }
+            },
+            {
+                "zip": [
+                    {
+                        "album": "Dialogues",
+                        "title": "Stern Stuff (with Mike Stern)",
+                        "ip": "82.235.163.40",
+                        "artist": "Jim Hall",
+                        "time": 135796967448742,
+                        "useragent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.17 (KHTML, like Gecko) Chrome/24.0.1312.45 Safari/537.17",
+                        "id": "06a3d18b3f9b51e55d3c978b0635b1738db99ad0"
+                    },
+                    {
+                        "album": "These Times",
+                        "title": "I Know You",
+                        "ip": "82.235.163.40",
+                        "artist": "Mike Stern",
+                        "time": 135796967448919,
+                        "useragent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.17 (KHTML, like Gecko) Chrome/24.0.1312.45 Safari/537.17",
+                        "id": "1296c212778f8984c16ca9e71a8d9c047ff7b6c8"
+                    },
+                    {
+                        "album": "Big Neighborhood",
+                        "title": "Song For Pepper",
+                        "ip": "82.235.163.40",
+                        "artist": "Mike Stern",
+                        "time": 135796967449056,
+                        "useragent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.17 (KHTML, like Gecko) Chrome/24.0.1312.45 Safari/537.17",
+                        "id": "13ab9d011e41f39e5d71aa34d0d9dc9cecbcb2f5"
+                    }
+                ]
+            }
+        ]
+    }
 
 ## <a name="authentication"></a>Authentication
 
@@ -526,13 +526,14 @@ The following table includes coordinated extensions and mimetypes. Preferred ext
 </tbody>
 </table>
 
-## Errors
+## <a name="errors"></a>Errors
 
-For any successful request, the server responds with HTTP status 200 and the result dictionary must not contain the key `error`. When any server-side error occurs (malformed request, authentication error, etc.), an appropriate HTTP error status is used. The result dictionary contains the key `error`, associated with a string describing what went wrong. For example, when an invalid token in supplied to an authenticated endpoint, the server could respond with HTTP status 403 and the following body:
+For any successful request, the server responds with `HTTP 200 OK` and the resultant object must not contain the key `error`. When any server-side error occurs (malformed request, authentication error, etc.), an appropriate HTTP error status is used. The result dictionary contains the key `error`, associated with a string describing the error. For example, when an invalid token in supplied to an authenticated endpoint, the server may respond with `HTTP 403 Forbidden` and the following body:
 
     {
-        "error": "authentication error"
+        "error": "Authentication error."
     }
 
 ## License
+
 This work is licensed under the [Creative Commons Attribution-ShareAlike 3.0 Unported License](http://git.zx2c4.com/ramc-spec/tree/COPYING).