-#  connectr 
+#  Connectr 
+[](https://travis-ci.org/mrmekon/connectr)
+[](https://ci.appveyor.com/project/mrmekon/connectr/branch/master)
+[](https://crates.io/crates/connectr)
-connectr is a Rust library and systray/menubar application for controlling and monitoring [Spotify Connect](https://www.spotify.com/se/connect/) devices.
+--
+### A super lightweight Spotify controller.
-**Note:** Spotify Premium is required to create an application. You must have Premium to use connectr.
+--
-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.
+Connectr is a tiny application that lets you quickly and easily see – or change – what's playing on your Spotify account.
-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.
+It's compatible with anything that supports [Spotify Connect](https://www.spotify.com/se/connect/): computers, mobiles, speakers, TVs, Playstations, etc.
-*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).
+***NOTE:*** Spotify Premium is required to use Spotify's remote control features. Free accounts do not work.
-### Development Status
-[](https://travis-ci.org/mrmekon/connectr)
-[](https://ci.appveyor.com/project/mrmekon/connectr/branch/master)
+It runs in the Mac menu bar (top right corner) or Windows system tray (bottom right corner...), and the Mac Touch Bar (the fancy touchscreen on new Macbook keyboards). It's just a little icon that pops up the controls when you need them, and hides away when you don't. Or just hover over it to see what's currently playing.
-Beta / Hobby / Experimental
+What it can do:
-### Code Status
-Sloppy; this is my first Rust.
+* Show what's playing
+* Play/pause
+* Skip tracks
+* Quick-play a saved 'preset'
+* Select playback device
+* Change volume
-### Cargo Crate
-[](https://crates.io/crates/connectr)
+Most importantly, it maintains a tiny memory footprint while running. ~10MB on a Mac, compared to 300-1000MB for the Spotify desktop app. You shouldn't need to buy extra RAM just to monitor what's playing on your speakers.
+
+For developers: the API for communicating with the Spotify backend is provided as a Rust library, available as a Cargo crate. Connectr exposes the official [Spotify 'Player' Web API](https://developer.spotify.com/web-api/web-api-connect-endpoint-reference/) for controlling Spotify Connect devices.
+
+***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). The librespot + connectr combo gives you a full Spotify playback experience in ~15MB of RAM. It's the most resource-efficient way to listen to Spotify.
+
+***NOTE:*** Connectr is not developed by Spotify and has nothing to do with their company.
+
+## Download
+
+*Binary releases are provided as a convenience. Building from source is preferred.*
+
+### Connectr v0.2.0
+#### [Mac OS X](https://github.com/mrmekon/connectr/releases/download/connectr-0.2.0/connectr-0.2.0.zip) (64-bit, md5: 6ec4481f67f62cce2c9c062890521444)
+#### [Windows 10](https://github.com/mrmekon/connectr/releases/download/connectr-0.2.0/connectr-0.2.0-win32.zip) (64-bit, md5: 1745ecb67bd5ef0822eeabd96d98dcde)
-### Platform Status
+## Screenshots
-The underlying library should be fully cross-platform, though I'm only testing x86_64 Windows and OS X.
+--
-*Web API Library*:
-Fully functional and pretty stable for the requirements of the connectr menu bar app. Error handling isn't extremely robust, and it doesn't implement retries or exponential backoff, which it should. The Spotify API can, of course, do plenty more than connectr exposes.
+<table><tr><td valign="top">
-*Systray/Menubar Application*:
-* Mac OS X - Done
-* Windows - Done
-* Linux - Maybe someday
+<center><strong>Mac OS X</strong></center></br>
+<center><img src="https://github.com/mrmekon/connectr/blob/master/docs/screenshot.png?raw=true" width="300"></center>
-### Screenshot
-<img src="https://github.com/mrmekon/connectr/blob/master/docs/screenshot.png" width="300">
-<img src="https://github.com/mrmekon/connectr/blob/master/docs/screenshot_windows.png" width="300">
+</td><td valign="top">
-### Build Instructions
+<center><strong>Windows 10</strong></center></br>
+<center><img src="https://github.com/mrmekon/connectr/blob/master/docs/screenshot_windows.png?raw=true" width="300"></center>
+
+</td></tr><tr><td colspan="2">
+
+<center><strong>Macbook Touch Bar</strong></center></br>
+<center><img src="https://github.com/mrmekon/connectr/blob/master/docs/screenshot_touchbar.png?raw=true"></center>
+
+</td></tr></table>
+
+--
+
+
+## Build Instructions
+
+You need to [download Rust](https://www.rustup.rs/) to build.
```
$ git clone https://github.com/mrmekon/connectr.git
$ cargo run
```
+## Usage / Help
+
On first launch, Connectr will open your web browser to a self-configuration page, and save its configuration to your system home directory. The configuration page will walk you through creating the necessary Spotify developer application.
### Spotify Developer Application configuration
-On the first launch, connectr will guide you through setting up a Spotify developer application. If you want to do it manually instead, or if something goes wrong, here are the instructions:
+On the first launch, Connectr will guide you through setting up a Spotify developer application. If you want to do it manually instead, or if something goes wrong, here are the instructions:
* Go to your [Spotify Applications](https://developer.spotify.com/my-applications/#!/applications/create) page (login with your Spotify credentials)
* Click "CREATE AN APP" in the upper-right corner
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)
+* **port** - Port to temporarily run web server on when requesting initial OAuth tokens (integer). Default is 5432. _ex: `port = 5432`_
#### [application]
-* client_id - Spotify web application's Client ID (string)
-* secret - Spotify web application's Client Secret (string)
+* **client_id** - Spotify web application's Client ID (string). _ex: `client_id = ABCABCABCABC123123123`_
+* **secret** - Spotify web application's Client Secret (string). _ex: `secret = DEFDEFDEFDEF456456456`_
#### [presets]
-* <preset 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._
+* **Your Preset Name** - Key is the display name of a playable preset, as it will appear in the menu. The value is a Spotify URI to play, in the _spotify:type:aLoNgUnIqUeIdENTIFier_ format. (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. You can leave it empty if you make your own config file._
+
+* **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
```
expire=1492766270
```
-### Progress
+### Feature Progress
| Feature | OS X | Windows | Linux |
| --- | --- | --- | --- |
| **System** |
| Persistent configuration | <ul><li> [x] </li></ul> | <ul><li> [x] </li></ul> | <ul><li> [ ] </li></ul> |
| System logging | <ul><li> [x] </li></ul> | <ul><li> [x] </li></ul> | <ul><li> [ ] </li></ul> |
-| Installer | <ul><li> [x] </li></ul> | <ul><li> [ ] </li></ul> | <ul><li> [ ] </li></ul> |
+