audius

    Dark Mode
Search:
Group by:

The audius module is simple wrapper to the Audius API (v1).

Audius is a decentralized music streaming service. (audius.co / audius.org)

The Audius API is entirely free to use.

We ask that you adhere to the guidelines in this doc and always credit artists.

Examples

import audius

# Create new Audius client.
let client = newAudius()

# Search users.
for user in client.searchUsers("Brownies"):
  echo "User found: " & user.name

# Create new user by id.
let user = client.getUser("nlGNe")
echo "User name: " & user.name &
    " Profile Picture: " & user.profilePicture.small

# List user's tracks.
for track in user.tracks:
  echo "User's Track: " & track.title

# List user's favorite tracks.
for favorite in user.favorites:
  echo "User's Favorite: " & favorite.title

# List user reposted tracks.
for repost in user.reposts:
  echo "User's Repost: " & repost.title

# List common user's tags.
for tag in user.tags:
  echo "User's Tag: " & tag

# Search playlists
for playlist in client.searchPlaylists("Hot & New"):
  echo "Palylist found: " & playlist.playlistName

# Create new playlist by id.
let playlist = client.getPlaylist("DOPRl")
echo "Playlist name:"

# List tracks in playlist.
for track in playlist.tracks:
  echo "Playlist's Track: " & track.title

# List trending tracks.
for track in client.trendingTracks(Genre.jazz, Time.week):
  echo track.title

Types

Audius = ref object
  client: HttpClient
  headers: HttpHeaders
  appName: string
  server: string
Audius API client. 
Artwork = object
  small*, medium*, big*: string

Cover photo schema

Profile picture

Track artwork schema

Playlist artwork schema

small = 150x & 640x, medium = 480x, big = 1000x & 2000x

User = object
  albumCount*, followeeCount*, followerCount*, playlistCount*, repostCount*,
  trackCount*: int
  bio*, handle*, id*, location*, name*: string
  coverPhoto*, profilePicture*: Artwork
  isVerified*: bool
  api: Audius
User schema 
Track = object
  trackArtwork: Artwork
  description*, genre*, id*, mood*, releaseDate*, tags*, title*: string
  repostCount*, favoriteCount*, duration*, playCount*: int
  downloadable*: bool
  user*: User
  api: Audius
Track schema 
Playlist = object
  playlistArtwork: Artwork
  description*, id*, playlistName*: string
  repostCount*, favoriteCount*, totalPlayCount*: int
  isAlbum*: bool
  user*: User
  api: Audius
Playlist schema 
Time {...}{.pure.} = enum
  week = "week", month = "month", allTime = "allTime", none = ""
Genre {...}{.pure.} = enum
  none = "", electronic, rock, metal, alternative, hipHopRap = "Hip-Hop%2FRap",
  experimental, punk, folk, pop, ambient, soundtrack, world, jazz, acoustic,
  funk, rbSoul = "R%26B%2FSoul", devotional, classical, reggae, podcasts,
  country, spokenWord = "Spoken+Word", comedy, blues, kids, audiobooks, latin

Procs

proc parseHook(s: string; i: var int; v: var Audius) {...}{.raises: [], tags: [].}
Warning: Do not use! This is a hook for jsony lib. 
proc renameHook(v: var Artwork; fieldName: var string) {...}{.raises: [], tags: [].}

Warning: Do not use! This is a hook for jsony lib.

Rename field: small = 150x & 640x, medium = 480x, big = 1000x & 2000x

proc newAudius(appName: string = "EXAMPLEAPP"): Audius {...}{.raises: [KeyError,
    Exception, LibraryError, SslError, IOError, OSError, JsonError, ValueError,
    HttpRequestError, TimeoutError, ProtocolError], tags: [RootEffect,
    ReadDirEffect, ReadEnvEffect, ReadIOEffect, WriteIOEffect, TimeEffect].}
This create a new Audius API (v1) client and select a host. 
proc getTrack(api: Audius; id: string): Track {...}{.raises: [KeyError, JsonError,
    ValueError, OSError, HttpRequestError, Exception, LibraryError, SslError,
    IOError, TimeoutError, ProtocolError],
    tags: [ReadIOEffect, RootEffect, WriteIOEffect, TimeEffect].}
Fetch a track. /tracks/{track_id} 
proc getStreamTrack(api: Audius; id: string): string {...}{.raises: [ValueError,
    OSError, HttpRequestError, Exception, LibraryError, SslError, IOError,
    TimeoutError, ProtocolError, KeyError],
    tags: [ReadIOEffect, RootEffect, WriteIOEffect, TimeEffect].}

Get the track's streamable mp3 file. /tracks/{track_id}/stream

Todo: Range header.

proc trendingTracks(api: Audius; genre: Genre = Genre.none;
                    time: Time = Time.none): seq[Track] {...}{.raises: [JsonError,
    ValueError, OSError, HttpRequestError, Exception, LibraryError, SslError,
    IOError, TimeoutError, ProtocolError, KeyError],
    tags: [ReadIOEffect, RootEffect, WriteIOEffect, TimeEffect].}
Gets the top 100 trending (most popular) tracks on Audius. /tracks/trending 
proc getPlaylist(api: Audius; id: string): Playlist {...}{.raises: [KeyError,
    JsonError, ValueError, OSError, HttpRequestError, Exception, LibraryError,
    SslError, IOError, TimeoutError, ProtocolError],
    tags: [ReadIOEffect, RootEffect, WriteIOEffect, TimeEffect].}
Fetch a playlist. /playlists/{playlist_id} 
proc searchPlaylists(api: Audius; query: string; onlyDowloadable = false): seq[
    Playlist] {...}{.raises: [JsonError, ValueError, OSError, HttpRequestError,
                         Exception, LibraryError, SslError, IOError,
                         TimeoutError, ProtocolError, KeyError],
                tags: [ReadIOEffect, RootEffect, WriteIOEffect, TimeEffect].}
Search for a playlist. /playlists/search 
proc tracks(playlist: Playlist): seq[Track] {...}{.raises: [JsonError, ValueError,
    OSError, HttpRequestError, Exception, LibraryError, SslError, IOError,
    TimeoutError, ProtocolError, KeyError],
    tags: [ReadIOEffect, RootEffect, WriteIOEffect, TimeEffect].}
Search for a track. /tracks/search 
proc getUser(api: Audius; id: string): User {...}{.raises: [KeyError, JsonError,
    ValueError, OSError, HttpRequestError, Exception, LibraryError, SslError,
    IOError, TimeoutError, ProtocolError],
    tags: [ReadIOEffect, RootEffect, WriteIOEffect, TimeEffect].}
Fetch a single user. /users/{user_id} 
proc searchUsers(api: Audius; query: string; onlyDowloadable = false): seq[User] {...}{.raises: [
    JsonError, ValueError, OSError, HttpRequestError, Exception, LibraryError,
    SslError, IOError, TimeoutError, ProtocolError, KeyError],
    tags: [ReadIOEffect, RootEffect, WriteIOEffect, TimeEffect].}
Search for a user. /users/search 
proc tracks(user: User): seq[Track] {...}{.raises: [JsonError, ValueError, OSError,
    HttpRequestError, Exception, LibraryError, SslError, IOError, TimeoutError,
    ProtocolError, KeyError], tags: [ReadIOEffect, RootEffect, WriteIOEffect,
                                     TimeEffect].}
Fetch a list of tracks for a user. /users/{user_id}/tracks 
proc favorites(user: User): seq[Track] {...}{.raises: [JsonError, ValueError,
    OSError, HttpRequestError, Exception, LibraryError, SslError, IOError,
    TimeoutError, ProtocolError, KeyError],
    tags: [ReadIOEffect, RootEffect, WriteIOEffect, TimeEffect].}
Fetch favorited tracks for a user. /users/{user_id}/favorites 
proc reposts(user: User): seq[Track] {...}{.raises: [JsonError, ValueError, OSError,
    HttpRequestError, Exception, LibraryError, SslError, IOError, TimeoutError,
    ProtocolError, KeyError], tags: [ReadIOEffect, RootEffect, WriteIOEffect,
                                     TimeEffect].}
Fetch reposted tracks for a user. /users/{user_id}/reposts

Iterators

iterator trendingTracks(api: Audius; genre: Genre = Genre.none;
                        time: Time = Time.none): Track {...}{.raises: [JsonError,
    ValueError, OSError, HttpRequestError, Exception, LibraryError, SslError,
    IOError, TimeoutError, ProtocolError, KeyError],
    tags: [ReadIOEffect, RootEffect, WriteIOEffect, TimeEffect].}
Gets the top 100 trending (most popular) tracks on Audius. /tracks/trending 
iterator searchPlaylists(api: Audius; query: string; onlyDowloadable = false): Playlist {...}{.raises: [
    JsonError, ValueError, OSError, HttpRequestError, Exception, LibraryError,
    SslError, IOError, TimeoutError, ProtocolError, KeyError],
    tags: [ReadIOEffect, RootEffect, WriteIOEffect, TimeEffect].}
Search for a playlist. /playlists/search 
iterator tracks(playlist: Playlist): Track {...}{.raises: [JsonError, ValueError,
    OSError, HttpRequestError, Exception, LibraryError, SslError, IOError,
    TimeoutError, ProtocolError, KeyError],
    tags: [ReadIOEffect, RootEffect, WriteIOEffect, TimeEffect].}
Search for a track. /tracks/search 
iterator searchUsers(api: Audius; query: string; onlyDowloadable = false): User {...}{.raises: [
    JsonError, ValueError, OSError, HttpRequestError, Exception, LibraryError,
    SslError, IOError, TimeoutError, ProtocolError, KeyError],
    tags: [ReadIOEffect, RootEffect, WriteIOEffect, TimeEffect].}
Search for a user. /users/search 
iterator tracks(user: User): Track {...}{.raises: [JsonError, ValueError, OSError,
    HttpRequestError, Exception, LibraryError, SslError, IOError, TimeoutError,
    ProtocolError, KeyError], tags: [ReadIOEffect, RootEffect, WriteIOEffect,
                                     TimeEffect].}
Fetch a list of tracks for a user. /users/{user_id}/tracks 
iterator favorites(user: User): Track {...}{.raises: [JsonError, ValueError, OSError,
    HttpRequestError, Exception, LibraryError, SslError, IOError, TimeoutError,
    ProtocolError, KeyError], tags: [ReadIOEffect, RootEffect, WriteIOEffect,
                                     TimeEffect].}
Fetch favorited tracks for a user. /users/{user_id}/favorites 
iterator reposts(user: User): Track {...}{.raises: [JsonError, ValueError, OSError,
    HttpRequestError, Exception, LibraryError, SslError, IOError, TimeoutError,
    ProtocolError, KeyError], tags: [ReadIOEffect, RootEffect, WriteIOEffect,
                                     TimeEffect].}
Fetch reposted tracks for a user. /users/{user_id}/reposts 
iterator tags(user: User): string {...}{.raises: [JsonError, ValueError, OSError,
    HttpRequestError, Exception, LibraryError, SslError, IOError, TimeoutError,
    ProtocolError, KeyError], tags: [ReadIOEffect, RootEffect, WriteIOEffect,
                                     TimeEffect].}

Warning: This don't work. API is broken !?

Fetch most used tags in a user's tracks. /users/{user_id}/tags


Made with Nim. Generated: 2022-01-28 00:04:21 UTC