i1-soundcloud/readme.md

tiny client to the soundcloud `i1/tracks#streams` resource

# i1

A module that returns a SoundCloud track's available streams (HTTP, RTMP, HLS) via the `SoundCloud/i1 API`.

## How did this come to be?

Although the SoundCloud public API shows a track is "streamable" or "downloadable" and its subsequent "source" links, the `SoundCloud/i1 API` reveals the true available HTTP, RTMP, and HLS resources currently hosted on its servers.

What started as an [issue](https://github.com/soundcloud/soundcloud-javascript/issues/12) became an interesting hunt for solutions. After inspecting some `Chrome` Network logs, I found there was an API endpoint that was not listed in SoundCloud's [HTTP API Reference](https://developers.soundcloud.com/docs/api/reference): `api/i1/tracks/{id}/streams`.

This library serves to make calls to the `Soundcloud/i1 API`, specifically to its tracks/streams resource.

## Show me the code.

The idea is this: require and instantiate from `i1`, plug in your API key, and pass a SoundCloud `permalink_url` through .getStreams(). It should return a data object that reveals the respective HTTP, RTMP, and HLS resources.

```js

// example/real-quick-example.js

var i1 = require('i1');

// Insert your own API key here.
var key = 'b45b1aa10f1ac2941910a7f0d10f8e28';

// Insert the track's permalink_url here.
var song = 'https://soundcloud.com/50_cent/g-unit-real-quick';

// Instantiate a new client.
var client = new i1({ key: key });

// Make a request to `api/i1/tracks/{id}/streams`
client.getStreams(song, function (err, body) {

// Something like this should appear:
// {
//    "rtmp_mp3_128_url":"rtmp://ec-rtmp-media.soundcloud.com/mp3:uaOLik82Zspo.128?9527d18f1063a01f059bf10590159adb10dea0996b8c0cdb674f9f2f261f859c9bff8d3c8732238a66f15c61c5e068290b0c519fff1361d99257121a85c6f690caa4dd3d5c2b16beb4196b4537e34344ffbc48975189c5cbda27",
//    "hls_mp3_128_url":"https://ec-hls-media.soundcloud.com/playlist/uaOLik82Zspo.128.mp3/playlist.m3u8?f10880d39085a94a0418a7e062b03d52bbdc0e179b82bde1d76ce4a21a456b0be48fb253f13741aebee9b76c5ebb0252a2985f4e99e7e24f6832aeca9e92fed5869d415f7d6d7d12285e6e2feea12bbc17dc7e6577b93ed50b8006c5"
// }
    console.log(body);
});

```

### Dependents
* request - for pulling down the data
* soundcloud-resolve - for resolving soundcloud permalink_urls

### Dev-Dependents
* getconfig - for storing api keys
* tap - for test assertions
* sinon - for test stubbing

### Todo
* Inform [soundcloud-javascript#issues](https://github.com/soundcloud/soundcloud-javascript/issues).
* API: In addition to permalink_url's, allow `getStreams()` to accept a track's `id`.
* Update test case to use sinon's Fake XHR.
* Generate documentation based on the comments.
* Include a Travis CI hook for automated testing.

### LICENSE
MIT