diff --git a/docs/API.md b/docs/API.md index 80df7a3..5ad5ccc 100644 --- a/docs/API.md +++ b/docs/API.md @@ -4,43 +4,67 @@ Just go to `/_/info` endpoint # API -To make use of it, instance must have API enabled of course. Currently, there is only one functionality present. If you are working on some cool project and wanna have more functionality here, let me know +To make use of it, instance must have API enabled of course. All responses are in JSON format if the request is successful. Errors are just returned as plaintext. Currently, there is few functionality present. If you are working on some cool project and wanna have more functionality here, let me know -## Searching +## Paginated endpoints -You can search with endpoint `/_/api/search`. Query parameters are: +Those endpoints return an object with properties: +- `collection`: List of the results on this page +- `total_results`: total results duh, maybe 0 on some endpoints +- `next_href`: Link to next page + +To go to next page, take the `next_href`, strip away everything until `?`, and pass that as `pagination` query parameter. Note that not all endpoints may support going to next page. + +You can also use `pagination` parameter to pass raw arguments into soundcloud api (for example, more advanced search filters, different initial result limit, etc) + +## GET `/_/api/search` + +Search for users, tracks or playlists. Query parameters are: - `q`: the query - `type`: `users`, `tracks`, or `playlists`. Required -- `pagination`: raw parameters to pass into soundcloud's api - -The response is in JSON format. To go to next page, take the `next_href` from result, strip away everything until `?`, and pass that as `pagination` parameter. +- `pagination`: [Read above](#paginated-endpoints) For example: `/_/api/search?q=test&type=tracks` to search for `tracks` named `test` +## GET `/_/api/track/:id/related` + +Get related tracks by ID. Pagination is supported here. Initial request returns upto 20 tracks + +For example: `/_/api/track/2014143543/related` to get tracks related to track with ID `2014143543` + +## GET `/_/api/tracks` + +Get tracks by ID in bulk. Pass the IDs comma-separated as `ids` query parameter. You can't request more than 50 tracks at once. The result is a list, which only contains the tracks which were successfully resolved + +For example: `/_/api/tracks?ids=2014143543,476907846`. This will only return one track, since 2nd ID is not a track ID + +## GET `/_/api/playlistByPermalink/:author/sets/:playlist` + +Get playlist by permalinks. + +For example: `/_/api/playlistByPermalink/lucybedroque/sets/unmusique` to get `unmusique` playlist from `lucybedroque` + # Other automation Doesn't require API to be enabled -## Download songs +## GET `/_/restream/:author/:track` -Restream must be enabled in the instance. The endpoint is `/_/restream//`. Query parameters are: +Restream must be enabled in the instance. This endpoint can be used to download or stream tracks. Query parameters are: - `metadata`: `true` or `false`. If `true`, soundcloak will inject metadata (author, track cover, track title, etc) into the audio file, but this may take a little bit more time - `audio`: `best`, `aac`, `opus`, or `mpeg`. [Read more here](AUDIO_PRESETS.md) +Restream converts the HLS playlist to an audio file on the fly serverside, optionally adding metadata. Please note that when `audio` is `opus` and `metadata` is `true`, it's not done on the fly, as metadata injection is a bit tricky there. + For example: `/_/restream/lucybedroque/speakers?metadata=true&audio=opus` to get the `opus` audio with `metadata` for song `speakers` by author `lucybedroque` -## Get search suggestions +## GET `/_/searchSuggestions` -The endpoint is `/_/searchSuggestions`. Query parameters are: -- `q`: the query - -The response is a list of search suggestions as strings in JSON format. +Pass your query as `q` query parameter For example: `/_/searchSuggestions?q=hi` to get search suggestions for `hi` -## Proxy images +## GET `/_/proxy/images` -ProxyImages must be enabled in the instance. - -Endpoint for images: `/_/proxy/images`. Put image url into `url` query parameter. Of course, this only proxies images from soundcloud cdn +ProxyImages must be enabled in the instance. Put image url into `url` query parameter. Of course, this only proxies images from soundcloud cdn diff --git a/go.mod b/go.mod index 20569cb..7add5a7 100644 --- a/go.mod +++ b/go.mod @@ -10,7 +10,7 @@ require ( github.com/gcottom/oggmeta v0.0.8 github.com/goccy/go-json v0.10.5 github.com/gofiber/fiber/v3 v3.0.0-beta.4 - github.com/valyala/fasthttp v1.62.0 + github.com/valyala/fasthttp v1.63.0 ) require ( diff --git a/go.sum b/go.sum index 4affbd5..dd215f0 100644 --- a/go.sum +++ b/go.sum @@ -62,8 +62,8 @@ github.com/tinylib/msgp v1.3.0 h1:ULuf7GPooDaIlbyvgAxBV/FI7ynli6LZ1/nVUNu+0ww= github.com/tinylib/msgp v1.3.0/go.mod h1:ykjzy2wzgrlvpDCRc4LA8UXy6D8bzMSuAF3WD57Gok0= github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw= github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc= -github.com/valyala/fasthttp v1.62.0 h1:8dKRBX/y2rCzyc6903Zu1+3qN0H/d2MsxPPmVNamiH0= -github.com/valyala/fasthttp v1.62.0/go.mod h1:FCINgr4GKdKqV8Q0xv8b+UxPV+H/O5nNFo3D+r54Htg= +github.com/valyala/fasthttp v1.63.0 h1:DisIL8OjB7ul2d7cBaMRcKTQDYnrGy56R4FCiuDP0Ns= +github.com/valyala/fasthttp v1.63.0/go.mod h1:REc4IeW+cAEyLrRPa5A81MIjvz0QE1laoTX2EaPHKJM= github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM= github.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg= github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU= diff --git a/lib/api/init.go b/lib/api/init.go index 0bebe70..a7c0828 100644 --- a/lib/api/init.go +++ b/lib/api/init.go @@ -5,18 +5,16 @@ import ( "net/url" "git.maid.zone/stuff/soundcloak/lib/cfg" - "git.maid.zone/stuff/soundcloak/lib/preferences" "git.maid.zone/stuff/soundcloak/lib/sc" "github.com/gofiber/fiber/v3" + json "github.com/goccy/go-json" ) -func Load(r *fiber.App) { - r.Get("/_/api/search", func(c fiber.Ctx) error { - prefs, err := preferences.Get(c) - if err != nil { - return err - } - +func Load(a *fiber.App) { + r := a.Group("/_/api") + + prefs := cfg.Preferences{ProxyImages: &cfg.False} + r.Get("/search", func(c fiber.Ctx) error { q := cfg.B2s(c.RequestCtx().QueryArgs().Peek("q")) t := cfg.B2s(c.RequestCtx().QueryArgs().Peek("type")) args := cfg.B2s(c.RequestCtx().QueryArgs().Peek("pagination")) @@ -55,4 +53,40 @@ func Load(r *fiber.App) { return c.SendStatus(404) }) + + r.Get("/track/:id/related", func(c fiber.Ctx) error { + args := cfg.B2s(c.RequestCtx().QueryArgs().Peek("pagination")) + if args == "" { + args = "?limit=20" + } + + p, err := (sc.Track{ID: json.Number(c.Params("id"))}).GetRelated("", prefs, args) + if err != nil { + log.Printf("[API] error getting related tracks for %d: %s\n", c.Params("id"), err) + return err + } + + return c.JSON(p) + }) + + r.Get("/playlistByPermalink/:author/sets/:playlist", func(c fiber.Ctx) error { + p, err := sc.GetPlaylist("", c.Params("author")+"/sets/"+c.Params("playlist")) + if err != nil { + log.Printf("[API] error getting %s playlist from %s: %s\n", c.Params("playlist"), c.Params("author"), err) + return err + } + + return c.JSON(p) + }) + + r.Get("/tracks", func(c fiber.Ctx) error { + ids := cfg.B2s(c.RequestCtx().QueryArgs().Peek("ids")) + t, err := sc.GetTracks("", ids) + if err != nil { + log.Printf("[API] error getting %s tracks: %s\n", ids, err) + return err + } + + return c.JSON(t) + }) } diff --git a/lib/sc/user.go b/lib/sc/user.go index 923f244..af6e059 100644 --- a/lib/sc/user.go +++ b/lib/sc/user.go @@ -37,7 +37,7 @@ type User struct { Verified bool `json:"verified"` Station string `json:"station_permalink"` - WebProfiles []Link + WebProfiles []Link `json:",omitempty"` } type Link struct {