soundcloudapi

package module
v0.1.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 22, 2022 License: GPL-3.0 Imports: 12 Imported by: 7

README

soundcloud-api

GoDoc

SoundCloud's v2 API reverse engineered for Go.

Notice

The SoundCloud api-v2 is an undocumented, internal API used by the web app at https://soundcloud.com.

SoundCloud is currently not allowing developers to register for applications, and using undocumented APIs is apparently breaking SoundCloud's ToS, use this at your own risk.

Quick Start

// You can specify certain options here if you want
sc, err := soundcloudapi.New(soundcloudapi.APIOptions{}) 

if err != nil {
    log.Fatal(err.Error())
}

track, err := sc.GetTrackInfo(soundcloudapi.GetTrackInfoOptions{
    URL: "https://soundcloud.com/track/infsdfo",
})

See the docs for more reference.

Error Handling

If an error is returned from SoundCloud's API, it will take the form of the FailedRequestError struct. You can use type assertions to access the status code or JSON error msg for your use case. Ex:

tracks, err := sc.GetTrackInfo(soundcloudapi.GetTrackInfoOptions{
    URL: "https://soundcloud.com/asdkfjhalsdhfl",
})

if failedRequest, ok := err.(*soundcloudapi.FailedRequestError); ok {
    if failedRequest.Status == 404 {
        fmt.Println("Could not find that track")
    }
    return
}

Paginated Queries

Functions like sc.Search() or sc.GetLikes() return a PaginatedQuery. PaginatedQuery.Collection contains the JSON of the items that matched the query, represented as a map[string]interface{}. You can use the provided functions to get the items in the form you want:

paginatedQuery, _ := sc.Search(soundcloudapi.SearchOptions{
    Query: "childish gambino"
})

tracks, _ := paginatedQuery.GetTracks() // Get the tracks of the response
playlists, _ := paginatedQuery.GetPlaylists() // Get the playlists of the response
likes, _ := paginatedQuery.GetLikes() // Get the likes of the response

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions 

func ConvertFirebaseLink(u string) (string, error)

ConvertFirebaseLink converts a link of the form (https://soundcloud.app.goo.gl/xxxxxxxx) to a regular SoundCloud link.

func ExtractIDFromPersonalizedTrackURL added in v0.0.4 

func ExtractIDFromPersonalizedTrackURL(url string) int64

ExtractIDFromPersonalizedTrackURL extracts the track ID from a personalized track URL, returns -1 if no track ID can be extracted

func FetchClientID 

func FetchClientID() (string, error)

FetchClientID fetches a SoundCloud client ID. This algorithm is adapted from: 

https://www.npmjs.com/package/soundcloud-key-fetch

func IsFirebaseURL added in v0.1.2 

func IsFirebaseURL(u string) bool

IsFirebaseURL returns true if the url is a SoundCloud Firebase url (has the following form: https://soundcloud.app.goo.gl/xxxxxxxx)

func IsMobileURL added in v0.1.4 

func IsMobileURL(u string) bool

IsMobileURL returns true if the url is a SoundCloud Firebase url (has the following form: https://m.soundcloud.com/xxxxxx)

func IsNewMobileURL added in v0.1.6 

func IsNewMobileURL(u string) bool

func IsPersonalizedTrackURL added in v0.1.1 

func IsPersonalizedTrackURL(url string) bool

IsPersonalizedTrackURL returns true if the provided url is a valid personalized track url. Ex/ https://soundcloud.com/discover/sets/personalized-tracks::sam:335899198

func IsPlaylistURL added in v0.1.2 

func IsPlaylistURL(u string) bool

IsPlaylistURL retuns true if the provided url is a valid SoundCloud playlist URL

func IsSearchURL added in v0.1.1 

func IsSearchURL(url string) bool

IsSearchURL returns true if the provided url is a valid search url

func IsURL added in v0.0.3 

func IsURL(url string, testMobile, testFirebase bool) bool

IsURL returns true if the provided url is a valid SoundCloud URL

func StripMobilePrefix added in v0.1.2 

func StripMobilePrefix(u string) string

StripMobilePrefix removes the prefix for mobile urls. Returns the same string if an error parsing the URL occurs

Types

type API added in v0.0.4 

type API struct {
	StripMobilePrefix   bool
	ConvertFirebaseURLs bool
	// contains filtered or unexported fields
}

API is a wrapper for the SoundCloud private API used internally for soundcloud.com

func New added in v0.0.4 

func New(options APIOptions) (*API, error)

New returns a pointer to a new SoundCloud API struct.

func (*API) ClientID added in v0.0.4 

func (sc *API) ClientID() string

ClientID returns the client ID

func (*API) ConvertNewMobileURL added in v0.1.7 

func (sc *API) ConvertNewMobileURL(url string) (string, error)

func (*API) DownloadTrack added in v0.0.4 

func (sc *API) DownloadTrack(transcoding Transcoding, dst io.Writer) error

DownloadTrack downloads the track specified by the given Transcoding's URL to dst

func (*API) GetDownloadURL added in v0.1.2 

func (sc *API) GetDownloadURL(url string, streamType string) (string, error)

GetDownloadURL retuns the URL to download a track. This is useful if you want to implement your own downloading algorithm. If the track has a publicly available download link, that link will be preferred and the streamType parameter will be ignored. streamType can be either "hls" or "progressive", defaults to "progressive"

func (*API) GetLikes added in v0.0.4 

func (sc *API) GetLikes(options GetLikesOptions) (*PaginatedQuery, error)

GetLikes returns a PaginatedQuery with the Collection field member as a list of tracks

func (*API) GetPlaylistInfo added in v0.0.4 

func (sc *API) GetPlaylistInfo(url string) (Playlist, error)

GetPlaylistInfo returns the info for a playlist

func (*API) GetTrackInfo added in v0.0.4 

func (sc *API) GetTrackInfo(options GetTrackInfoOptions) ([]Track, error)

GetTrackInfo returns the info for the track given tracks

If URL is supplied, it will return the info for a single track given by that url. If an array of ids is supplied, it will return an array of track info.

WARNING: Private tracks will not be fetched unless options.PlaylistID and options.PlaylistSecretToken are provided.

func (*API) GetUser added in v0.0.8 

func (sc *API) GetUser(options GetUserOptions) (User, error)

GetUser returns a User

func (*API) IsURL added in v0.1.4 

func (sc *API) IsURL(url string) bool

IsURL is a shorthand for IsURL(url, sc.StripMobilePrefix, sc.ConvertFirebaseURLs)

func (*API) Search added in v0.0.7 

func (sc *API) Search(options SearchOptions) (*PaginatedQuery, error)

Search returns a PaginatedQuery for searching a specific query

func (*API) SetClientID added in v0.0.4 

func (sc *API) SetClientID(clientID string)

SetClientID sets the client ID

type APIOptions added in v0.1.3 

type APIOptions struct {
	ClientID            string       // optional and a new one will be fetched if not provided
	HTTPClient          *http.Client // the HTTP client to make requests with
	StripMobilePrefix   bool         // whether or not to convert mobile URLs to regular URLs
	ConvertFirebaseURLs bool         // whether or not to convert SoundCloud firebase URLs to regular URLs
}

APIOptions are the options for creating an API struct

type DownloadURLResponse added in v0.1.5 

type DownloadURLResponse struct {
	URL string `json:"redirectUri"`
}

DownloadURLResponse is the JSON respose of retrieving media information of a publicly downloadable track

type FailedRequestError added in v0.0.5 

type FailedRequestError struct {
	Status int
	ErrMsg string
}

FailedRequestError is an error response from the SoundCloud API

func (*FailedRequestError) Error added in v0.0.5 

func (f *FailedRequestError) Error() string

type GetLikesOptions added in v0.0.4 

type GetLikesOptions struct {
	ProfileURL string // URL to the user's profile (will use this or ID to choose user)
	ID         int64  //  User's ID if you have it
	Limit      int    // How many tracks to return (defaults to 10)
	// This is for pagination. It should be the value of PaginatedQuery.NextHref or an empty string for no pagination
	Offset string
	Type   string // What type of resource to return. One of ["track", "playlist", "all"]. Defaults to "all"
}

GetLikesOptions are the options for getting a user's likes.

type GetTrackInfoOptions 

type GetTrackInfoOptions struct {
	URL                 string
	ID                  []int64
	PlaylistID          int64
	PlaylistSecretToken string
}

GetTrackInfoOptions can contain the URL of the track or the ID of the track. PlaylistID and PlaylistSecretToken are necessary to retrieve private tracks in private playlists.

type GetUserOptions added in v0.0.4 

type GetUserOptions struct {
	ProfileURL string
	ID         int64
}

GetUserOptions contains either the profile url of the user or the ID of the user

type Kind added in v0.1.0 

type Kind string

Kind is a string 

const KindAlbum Kind = "albums"

KindAlbum is the kind for an album 

const KindPlaylist Kind = "playlist"

KindPlaylist is the kind for a playlist 

const KindTrack Kind = "tracks"

KindTrack is the kind for a Track 

const KindUser Kind = "users"

KindUser is the kind for a user

type Like added in v0.0.4 

type Like struct {
	CreatedAt string   `json:"created_at"`
	Kind      string   `json:"kind"`
	Track     Track    `json:"track"`
	Playlist  Playlist `json:"playlist"`
}

Like is the JSON response for a like

type Media 

type Media struct {
	Transcodings []Transcoding `json:"transcodings"`
}

Media contains an array of transcoding for a track

type MediaURLResponse added in v0.0.3 

type MediaURLResponse struct {
	URL string `json:"url"`
}

MediaURLResponse is the JSON response of retrieving media information of a track

type PaginatedQuery added in v0.0.4 

type PaginatedQuery struct {
	Collection   []map[string]interface{} `json:"collection"`
	TotalResults int                      `json:"total_results"`
	NextHref     string                   `json:"next_href"`
	QueryURN     string                   `json:"query_urn"`
}

PaginatedQuery is the JSON response for a paginated query

func (*PaginatedQuery) GetLikes added in v0.1.0 

func (pq *PaginatedQuery) GetLikes() ([]Like, error)

GetLikes returns any of the items in the PaginatedQuery's collection that match the Like struct type

func (*PaginatedQuery) GetPlaylists added in v0.1.0 

func (pq *PaginatedQuery) GetPlaylists() ([]Playlist, error)

GetPlaylists returns any of the items in the PaginatedQuery's collection that match the Playlist struct type

func (*PaginatedQuery) GetTracks added in v0.1.0 

func (pq *PaginatedQuery) GetTracks() ([]Track, error)

GetTracks returns any of the items in the PaginatedQuery's collection that match the Track struct type

type Playlist 

type Playlist struct {
	ArtworkURL     string  `json:"artwork_url"`
	CreatedAt      string  `json:"created_at"`
	Description    string  `json:"description"`
	DurationMS     int64   `json:"duration"`
	EmbeddeableBy  string  `json:"embeddable_by"`
	Genre          string  `json:"genre"`
	ID             int64   `json:"id"`
	Kind           string  `json:"kind"`
	LabelName      string  `json:"label_name"`
	LastModified   string  `json:"last_modified"`
	License        string  `json:"license"`
	LikesCount     int     `json:"likes_count"`
	ManagedByFeeds bool    `json:"managed_by_feeds"`
	Permalink      string  `json:"permalink"`
	PermalinkURL   string  `json:"permalink_url"`
	Public         bool    `json:"public"`
	SecretToken    string  `json:"secret_token"`
	Sharing        string  `json:"private"`
	TagList        string  `json:"tag_list"`
	Title          string  `json:"title"`
	URI            string  `json:"uri"`
	UserID         int64   `json:"user_id"`
	SetType        string  `json:"set_type"`
	IsAlbum        bool    `json:"is_album"`
	PublishedAt    string  `json:"published_at"`
	DisplayDate    string  `json:"display_date"`
	User           User    `json:"user"`
	Tracks         []Track `json:"tracks"`
	TrackCount     int     `json:"track_count"`
}

Playlist represents the JSON response of a playlist

type SearchOptions added in v0.0.7 

type SearchOptions struct {
	// This is the NextHref property of PaginatedQuery structs
	QueryURL string
	Query    string
	// Number of items to return
	Limit int
	// Number of items to offset by (for pagination)
	Offset int
	// The type of item to return
	Kind Kind
}

SearchOptions are the parameters for executing a search

type Track 

type Track struct {
	Kind              string `json:"kind"`
	MonetizationModel string `json:"monetization_model"`
	ID                int64  `json:"id"`
	Policy            string `json:"polic"`
	CommentCount      int64  `json:"comment_count"`
	FullDurationMS    int64  `json:"full_duration"`
	Downloadable      bool   `json:"downloadable"`
	HasDownloadsLeft  bool   `json:"has_downloads_left"`
	CreatedAt         string `json:"created_at"`
	Description       string `json:"description"`
	Media             Media  `json:"media"`
	Title             string `json:"title"`
	DurationMS        int64  `json:"duration"`
	ArtworkURL        string `json:"artwork_url"`
	Public            bool   `json:"public"`
	Streamable        bool   `json:"streamable"`
	TagList           string `json:"tag_list"`
	Genre             string `json:"genre"`
	RepostsCount      int64  `json:"reposts_count"`
	LabelName         string `json:"label_name"`
	LastModified      string `json:"last_modified"`
	Commentable       bool   `json:"commentable"`
	URI               string `json:"uri"`
	DownloadCount     int64  `json:"download_count"`
	LikesCount        int64  `json:"likes_count"`
	DisplayDate       string `json:"display_date"`
	UserID            int64  `json:"user_id"`
	WaveformURL       string `json:"waveform_url"`
	Permalink         string `json:"permalink"`
	PermalinkURL      string `json:"permalink_url"`
	PlaybackCount     int64  `json:"playback_count"`
	SecretToken       string `json:"secret_token"`
	User              User   `json:"user"`
}

Track represents the JSON response of a track's info

type Transcoding 

type Transcoding struct {
	URL     string            `json:"url"`
	Preset  string            `json:"preset"`
	Snipped bool              `json:"snipped"`
	Format  TranscodingFormat `json:"format"`
}

Transcoding contains information about the transcoding of a track

type TranscodingFormat 

type TranscodingFormat struct {
	Protocol string `json:"protocol"`
	MimeType string `json:"mime_type"`
}

TranscodingFormat contains the protocol by which the track is delivered ("progressive" or "HLS"), and the mime type of the track

type User 

type User struct {
	ID              int64  `json:"id"`
	AvatarURL       string `json:"avatar_url"`
	City            string `json:"city"`
	CommentsCount   int64  `json:"comments_count"`
	CountryCode     string `json:"country_code"`
	CreatedAt       string `json:"created_at"`
	Description     string `json:"description"`
	FollowersCount  int64  `json:"followers_count"`
	FollowingsCount int64  `json:"followings_count"`
	FirstName       string `json:"first_name"`
	LastName        string `json:"last_name"`
	PermalinkURL    string `json:"permalink_url"`
	URI             string `json:"uri"`
	Username        string `json:"username"`
	Kind            string `json:"kind"`
	Likes           int    `json:"likes_count"`
	PlaylistLikes   int    `json:"playlist_likes_count"`
	Verified        bool   `json:"verified"`
}

User represents the JSON payload for user data

Source Files

View all Source files

Directories

Path Synopsis
example
likes
playlist
search
track
user

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.