docs(track): add

cloudr-app · Feb 22, 2021 · 678a4d6 · 678a4d6
1 parent 1d7d166
commit 678a4d6
Show file tree

Hide file tree

Showing 6 changed files with 173 additions and 79 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -3,6 +3,7 @@
     "Likesv",
     "Playlistv",
     "Tracksv",
+    "Trackv",
     "Userv",
     "lcov",
     "npmrc",

diff --git a/docs/api/index.md b/docs/api/index.md
@@ -1,11 +1,44 @@
 # Entities
 
+## track
+
+- **Arguments**:
+
+  - identifier: `{string | number}` URL, URL path or ID
+  - client_id?: `{string}` client_id for APIv2
+
+- **Returns**: `Promise<Trackv2>`
+  ::: details example track Object
+
+  <<< @/docs/snippets/track.get.json
+
+  :::
+
+- **Usage**:
+  Request info about a track by either SoundCloud URL or ID.
+  If you use a string as identifier it resolves the data via scraping.
+
+  If you use a number (user ID) it calls the APIv2 directly. In that case it's recommended
+  to supply a `client_id` for APIv2 to save on one request which would resolve one for you.
+
+  Use [`util.getClientIDv2`](/api/util.html#getclientidv2) to get a `client_id` for APIv2.
+
+- **Example**:
+
+  ```ts
+  import { user } from "opensoundcloud"
+
+  const track = await track("noisia/tentacles-1")
+
+  console.log(track.id) //> 313447871
+  ```
+
 ## user
 
 - **Arguments**:
 
-  - identifier: `{string | number} URL, URL path or ID`
-  - client_id?: `{string} [client_id for APIv2]`
+  - identifier: `{string | number}` URL, URL path or ID
+  - client_id?: `{string}` client_id for APIv2
 
 - **Returns**: `Promise<Userv2>`
   ::: details example user Object
@@ -39,10 +72,10 @@
 
 - **Arguments**:
 
-  - identifier: `{string | number} URL, URL path or ID`
+  - identifier: `{string | number}` URL, URL path or ID
   - options?: `{Object}`
-    - limit?: `{number} Limit the amount of tracks returned. Defaults to 50.`
-    - client_id?: `{string} client_id for APIv2`
+    - limit?: `{number}` Limit the amount of tracks returned. Defaults to 20.
+    - client_id?: `{string}` client_id for APIv2
 
 - **Returns**: `Promise<PaginatedResponse<TrackElement[]>>`
   ::: details example tracks Object
@@ -75,10 +108,10 @@
 
 - **Arguments**:
 
-  - identifier: `{string | number} URL, URL path or ID`
+  - identifier: `{string | number}` URL, URL path or ID
   - options?: `{Object}`
-    - limit?: `{number} Limit the amount of likes returned. Defaults to 50.`
-    - client_id?: `{string} client_id for APIv2`
+    - limit?: `{number}` Limit the amount of tracks returned. Defaults to 20.
+    - client_id?: `{string}` client_id for APIv2
 
 - **Returns**: `Promise<PaginatedResponse<UserLikesv2Element[]>>`
   ::: details example likes Object
@@ -109,8 +142,8 @@
 
 - **Arguments**:
 
-  - identifier: `{string | number} URL, URL path or ID`
-  - client_id?: `{string} [client_id] client_id for APIv2`
+  - identifier: `{string | number}` URL, URL path or ID
+  - client_id?: `{string}` client_id for APIv2
 
 - **Returns**: `Promise<Playlistv2>`
   ::: details example playlist Object
@@ -145,8 +178,8 @@
 
   - query: `{string}`
   - options?: `{Object}`
-    - limit?: `{number} Limit the amount of items returned. Defaults to 20.`
-    - client_id?: `{string} client_id for APIv2`
+    - limit?: `{number}` Limit the amount of tracks returned. Defaults to 20.
+    - client_id?: `{string}` client_id for APIv2
 
 - **Returns**: `Promise<PaginatedResponse<SearchResult[]>>`
   ::: details example search response Object

diff --git a/docs/guide/index.md b/docs/guide/index.md
@@ -49,67 +49,8 @@ both will return the users data, which looks something like this:
 
 ::: details userData
 
-```json
-{
-  "avatar_url": "https://i1.sndcdn.com/avatars-000467483484-sxhijk-large.jpg",
-  "city": "",
-  "comments_count": 95,
-  "country_code": null,
-  "created_at": "2013-07-23T12:21:57Z",
-  "creator_subscriptions": [
-    {
-      "product": {
-        "id": "free"
-      }
-    }
-  ],
-  "creator_subscription": {
-    "product": {
-      "id": "free"
-    }
-  },
-  "description": "i like wubs",
-  "followers_count": 50,
-  "followings_count": 167,
-  "first_name": "",
-  "full_name": "",
-  "groups_count": 0,
-  "id": 51999125,
-  "kind": "user",
-  "last_modified": "2019-01-29T21:22:49Z",
-  "last_name": "",
-  "likes_count": 581,
-  "playlist_likes_count": 2,
-  "permalink": "vaaski",
-  "permalink_url": "https://soundcloud.com/vaaski",
-  "playlist_count": 8,
-  "reposts_count": null,
-  "track_count": 1,
-  "uri": "https://api.soundcloud.com/users/51999125",
-  "urn": "soundcloud:users:51999125",
-  "username": "vaaski",
-  "verified": false,
-  "visuals": {
-    "urn": "soundcloud:users:51999125",
-    "enabled": true,
-    "visuals": [
-      {
-        "urn": "soundcloud:visuals:50729877",
-        "entry_time": 0,
-        "visual_url": "https://i1.sndcdn.com/visuals-000051999125-yLyaqm-original.jpg"
-      }
-    ],
-    "tracking": null
-  },
-  "badges": {
-    "pro": false,
-    "pro_unlimited": false,
-    "verified": false
-  },
-  "url": "/vaaski"
-}
-```
+<<< @/docs/snippets/user.get.json
 
 :::
 
-Get more info in the [API section](/api)
+Get more info in the [API section](/api)
diff --git a/docs/snippets/track.get.json b/docs/snippets/track.get.json
@@ -0,0 +1,119 @@
+{
+  "artwork_url": "https://i1.sndcdn.com/artworks-Yo3mH7MYaXkR-0-large.png",
+  "caption": null,
+  "commentable": true,
+  "comment_count": 5,
+  "created_at": "2017-03-20T16:24:44Z",
+  "description": null,
+  "downloadable": false,
+  "download_count": 0,
+  "duration": 191129,
+  "full_duration": 191129,
+  "embeddable_by": "all",
+  "genre": "Electronic",
+  "has_downloads_left": true,
+  "id": 313447871,
+  "kind": "track",
+  "label_name": "Vision Recordings",
+  "last_modified": "2018-11-12T16:06:05Z",
+  "license": "all-rights-reserved",
+  "likes_count": 596,
+  "permalink": "tentacles-1",
+  "permalink_url": "https://soundcloud.com/noisia/tentacles-1",
+  "playback_count": 16506,
+  "public": true,
+  "publisher_metadata": {
+    "id": 313447871,
+    "urn": "soundcloud:tracks:313447871",
+    "artist": "Noisia",
+    "album_title": "Outer Edges",
+    "contains_music": true,
+    "upc_or_ean": "5060448297771",
+    "isrc": "NLCK41032641",
+    "explicit": false,
+    "p_line": "2016 Vision Recordings",
+    "p_line_for_display": "℗ 2016 Vision Recordings",
+    "c_line": "2016 Vision Recordings",
+    "c_line_for_display": "© 2016 Vision Recordings",
+    "release_title": "Tentacles"
+  },
+  "purchase_title": null,
+  "purchase_url": null,
+  "release_date": "2016-08-05T00:00:00Z",
+  "reposts_count": 34,
+  "secret_token": null,
+  "sharing": "public",
+  "state": "finished",
+  "streamable": true,
+  "tag_list": "\"Drum & Bass\"",
+  "title": "Tentacles",
+  "track_format": "single-track",
+  "uri": "https://api.soundcloud.com/tracks/313447871",
+  "urn": "soundcloud:tracks:313447871",
+  "user_id": 116681,
+  "visuals": null,
+  "waveform_url": "https://wave.sndcdn.com/q1WquQVdelm3_m.json",
+  "display_date": "2016-08-05T00:00:00Z",
+  "media": {
+    "transcodings": [
+      {
+        "url": "https://api-v2.soundcloud.com/media/soundcloud:tracks:313447871/c8579861-49ae-4e7e-9318-d52f10fee4fb/stream/hls",
+        "preset": "mp3_standard",
+        "duration": 191129,
+        "snipped": false,
+        "format": {
+          "protocol": "hls",
+          "mime_type": "audio/mpeg"
+        },
+        "quality": "sq"
+      },
+      {
+        "url": "https://api-v2.soundcloud.com/media/soundcloud:tracks:313447871/c8579861-49ae-4e7e-9318-d52f10fee4fb/stream/progressive",
+        "preset": "mp3_standard",
+        "duration": 191129,
+        "snipped": false,
+        "format": {
+          "protocol": "progressive",
+          "mime_type": "audio/mpeg"
+        },
+        "quality": "sq"
+      },
+      {
+        "url": "https://api-v2.soundcloud.com/media/soundcloud:tracks:313447871/87a679d9-9245-40e0-a21f-9c042a267861/stream/hls",
+        "preset": "opus_0_0",
+        "duration": 191129,
+        "snipped": false,
+        "format": {
+          "protocol": "hls",
+          "mime_type": "audio/ogg; codecs=\"opus\""
+        },
+        "quality": "sq"
+      }
+    ]
+  },
+  "monetization_model": "AD_SUPPORTED",
+  "policy": "MONETIZE",
+  "user": {
+    "avatar_url": "https://i1.sndcdn.com/avatars-000451809714-n5njwk-large.jpg",
+    "first_name": "",
+    "followers_count": 3954040,
+    "full_name": "",
+    "id": 116681,
+    "kind": "user",
+    "last_modified": "2021-01-13T12:34:24Z",
+    "last_name": "",
+    "permalink": "noisia",
+    "permalink_url": "https://soundcloud.com/noisia",
+    "uri": "https://api.soundcloud.com/users/116681",
+    "urn": "soundcloud:users:116681",
+    "username": "NOISIA",
+    "verified": true,
+    "city": "",
+    "country_code": null,
+    "badges": {
+      "pro": false,
+      "pro_unlimited": true,
+      "verified": true
+    }
+  }
+}
diff --git a/src/track.ts b/src/track.ts
@@ -1,4 +1,4 @@
-import type { Track } from "../types/track"
+import type { Trackv2 } from "../types/track"
 import type { ClientIDv2, URLorID } from "../types"
 
 import ky from "ky-universal"
@@ -9,12 +9,12 @@ import { APIv2, getClientIDv2, scrapeData, ScrapeIDs, urlify } from "./util"
  * @param id A track ID
  * @param client_id client_id for APIv2
  */
-const getByID = async (id: number, client_id: ClientIDv2): Promise<Track> => {
+const getByID = async (id: number, client_id: ClientIDv2): Promise<Trackv2> => {
   const url = urlify(`tracks/${id}`, APIv2)
   const searchParams = { client_id }
 
   const data = await ky(url, { searchParams })
-  return (await data.json()) as Track
+  return (await data.json()) as Trackv2
 }
 
 /**
@@ -27,7 +27,7 @@ const getByURL = async (url: string) => {
   if (!trackData) throw new Error("No track data found.")
 
   const [data] = trackData.data
-  return data as Track
+  return data as Trackv2
 }
 
 /**
@@ -38,7 +38,7 @@ const getByURL = async (url: string) => {
  * @param identifier A track URL or ID
  * @param client_id Optional client_id for APIv2.
  */
-const track = async (identifier: URLorID, client_id?: ClientIDv2): Promise<Track> => {
+const track = async (identifier: URLorID, client_id?: ClientIDv2): Promise<Trackv2> => {
   if (typeof identifier === "string") return await getByURL(identifier)
 
   if (typeof identifier === "number") {

diff --git a/types/track.d.ts b/types/track.d.ts
@@ -1,6 +1,6 @@
 // generated with https://app.quicktype.io?share=9Fd3zZTCel75c1MlXFjU
 
-export interface Track {
+export interface Trackv2 {
   artwork_url: null | string
   caption: null
   commentable: boolean