-# Connectr
+# connectr
-Connectr is a Rust library and systray/menubar application for controlling and monitoring Spotify Connect devices.
+connectr is a Rust library and systray/menubar application for controlling and monitoring Spotify Connect devices.
+As a library, connectr exposes the official [Spotify 'Player' Web API](https://developer.spotify.com/web-api/web-api-connect-endpoint-reference/) for controlling Spotify Connect devices.
+As an application, connectr provides a minimal "systray" application to observe the currently playing track, control Spotify playback, switch playback devices, and start preset playlists. The goal is very low memory usage, so the basic Spotify functionality can always be available without keeping the massive Spotify desktop application resident in memory.
+
+*Note:* connectr is not an audio playback tool; it's just a remote control. Spotify has not publicly released a library for implementing audio playback with Spotify Connect support. There's a reverse engineering effort, coincidentally also in Rust, at [librespot](https://github.com/plietar/librespot).
+
+### Development Status
+Alpha / Hobby / Experimental
+
+### Code Status
+Sloppy; this is my first Rust.
+
+### Platform Status
+
+The underlying library should be fully cross-platform, though I'm not actually testing that yet. Let me know if you run it on an ARM; I'd like to know if that works.
+
+*Systray/Menubar Application*:
+* Mac OS X - Mostly done
+* Windows - Coming next
+* Linux - Maybe, but I don't use a desktop environment so I don't really care
+
+### Screenshot
+<img src="https://github.com/mrmekon/connectr/blob/master/docs/screenshot.png" width="300">
+
+### Instructions
+
+No binaries are provided. You must build from source with Cargo.
+
+Create a Spotify application here: https://developer.spotify.com/my-applications
+**Note:** Spotify Premium is required to create an application. You must have Premium to use connectr.
+You must add 'http://127.0.0.1:5432' as a Redirect URI for your application.
+Copy the Client ID and Client Secret to connectr's configuration file (see below).
+
+Something like this:
+```
+$ git clone https://github.com/mrmekon/connectr.git
+$ cd connectr
+$ cp connectr.ini.in ~/.connectr.ini
+$ ./clientid_prompt.sh
+$ cargo run
+```
+
+You must provide your Spotify application's client ID and secret in connectr's configuration file. This is handled by the `clientid_prompt.sh` script, or can be done manually.
+
+**Note:** connectr uses `~/.connectr.ini` if it exists. If it does _not_ exist, connectr will fallback to trying `connectr.ini` in the directory it is run from. If built as an OS X application, connectr will create `~/.connectr.ini` on first launch, but will fail to run until you add your Client ID and Secret. The included script `clientid_prompt.sh` can optionally be used to generate `~/.connectr.ini`; it will prompt for your Client ID and Secret when run. A template is provided in `connectr.ini.in`.
+
+### Configuration file (connectr.ini) format
+
+connectr's configuration is read from a regular INI file with these sections:
+
+#### [connectr]
+* port - Port to temporarily run web server on when requesting initial OAuth tokens (integer)
+
+#### [application]
+* client_id - Spotify web application's Client ID (string)
+* secret - Spotify web application's Client Secret (string)
+
+#### [presets]
+* [name] - Key name is the display name of a playable preset, the value must be a Spotify URI to play. (string)
+
+_ex: `Bakesale=spotify:album:70XjdLKH7HHsFVWoQipP0T` will show as 'Bakesale' in the menu, and will play the specified Sebadoh album when clicked._
+
+#### [tokens]
+* access - Spotify Web API access token
+* refresh - Spotify Web API refresh token
+* expire - Expiration time (UTC) for access token
+
+_note: this section is auto-generated and auto-updated at runtime_
+
+#### Example connectr.ini
+```
+[connectr]
+port=5432
+
+[application]
+secret=xxxxxyyyyyaaaaabbbbbcccccddddd
+client_id=xXxXxyYyYynNnNnNmMmMmMpPpPpP
+
+[presets]
+Discover Weekly=spotify:user:spotify:playlist:37i9dQZEVXcOmDhsenkuCu
+Edge Detector=spotify:user:mrmekon:playlist:4SKkpDbZwNGklpIILmEZAg
+Play Today=spotify:user:mrmekon:playlist:4c8eKK6kKrcdt1HToEX7Jc
+
+[tokens]
+access=this-is-autogenerated
+refresh=this-is-also-autogenerated
+expire=1492766270
+```
### Progress
| Skip next/previous | <ul><li> [x] </li></ul> | <ul><li> [x] </li></ul> | <ul><li> [x] </li></ul> |
| Seek in track | <ul><li> [x] </li></ul> | <ul><li> [x] </li></ul> | <ul><li> [x] </li></ul> |
| Change volume | <ul><li> [x] </li></ul> | <ul><li> [x] </li></ul> | <ul><li> [x] </li></ul> |
+| Change repeat state | <ul><li> [x] </li></ul> | <ul><li> [x] </li></ul> | <ul><li> [x] </li></ul> |
+| Change shuffle state | <ul><li> [x] </li></ul> | <ul><li> [x] </li></ul> | <ul><li> [x] </li></ul> |
+| Fetch album art | <ul><li> [ ] </li></ul> | <ul><li> [ ] </li></ul> | <ul><li> [ ] </li></ul> |
| |
| |
| **UI** |