Soundcloud is a music distribution platform that operates legally and has gained significant momentum in recent years; Soundcloud has many features that seem more like social networks, such as a comments section, users, favorites, sharing, etc.; it also has an API that we can integrate into our applications; you can check the following link Soundcloud Widget API and see everything it offers.
What is interesting for us as developers is that SoundCloud offers an API that we can easily integrate into our web applications. In my case, when I started working with it, what caught my attention the most was the possibility of using its enormous music library without worrying about legal issues, something that is usually a headache when working with music in web projects.
In this article, we are going to work with the API provided for JavaScript. The most interesting or important thing about this API is using its immense library of songs in our application without needing to worry about legal issues through widgets, which is the most practical option if you want to play music without dealing with OAuth, tokens, or complex backends.
What is SoundCloud and why use its API in JavaScript
The SoundCloud API allows developers to access tracks, users, playlists, and official players from external applications. This opens the door to:
- Creating custom players
- Displaying songs or lists dynamically
- Reacting to playback events
- Integrating music legally into a website
SoundCloud is especially useful when the goal is to display and play music directly on the frontend, without the need to manage complex authentication systems.
SoundCloud API vs. Widget API: key differences
This is where many people get confused (and Reddit is full of examples ).
SoundCloud API / SDK
- Requires client_id
- In many cases needs OAuth
- Allows access to detailed data (users, albums, tracks)
- Can return 401 / 403 errors if not configured correctly
SoundCloud Widget API (the one we use here)
- Does not need OAuth
- Works through an official iframe
- 100% legal playback
- Controllable from JavaScript with events
In my case, I opted for the Widget API because I wanted to integrate music quickly into a website without logins or tokens, and it was the right decision.
How to integrate SoundCloud into a website with JavaScript
The first thing we must do is include the SoundCloud JavaScript API:
<script src="https://w.soundcloud.com/player/api.js"></script>Creating the player iframe
The SoundCloud player works over an iframe. We can create it dynamically or define it in the HTML:
<iframe class="iframe" width="100%" height="166" scrolling="no" frameborder="no"></iframe>Now we can use the SC.Widget method provided by the JavaScript API to integrate the widgets as follows:
var widgetUrl = "http://api.soundcloud.com/users/1539950/favorites";
var iframe = document.querySelector('.iframe');
iframe.src = location.protocol + "//w.soundcloud.com/player/?url=" + widgetUrl;
var widget = SC.Widget(iframe);Initializing SC.Widget correctly
Once we have the iframe, we initialize the widget:
var widget = SC.Widget(iframe);From here, we can control playback and listen to events from JavaScript.
Controlling the SoundCloud player from JavaScript + Examples
The Soundcloud API in JavaScript has a large number of events as we can see below:
SC.Widget.Events.LOAD_PROGRESSExecutes periodically while the song is being loaded.SC.Widget.Events.PLAY_PROGRESSExecutes periodically while the song is being played.SC.Widget.Events.PLAYExecutes when the song plays.SC.Widget.Events.PAUSEExecutes when the song is paused.SC.Widget.Events.FINISHExecutes when the song finishes playback.SC.Widget.Events.READYWhen the widget is ready.
In my opinion, the most interesting or useful of all could be the one that determines when the song ended, since from this we can establish a series of actions such as loading other songs, showing an advertisement, etc:
widget.bind(SC.Widget.Events.FINISH, function (eventData) { // do something });Detecting when a song ends (FINISH)
This is the most useful event. When I discovered that I could detect the end of a song, I was able to automate several interesting actions.
widget.bind(SC.Widget.Events.FINISH, function (eventData) { // do something when the song ends });
Thanks to this you can:
- Load another song
- Simulate a playlist
- Show ads
- Trigger animations or UI changes
Detecting the Ready state of the widget music playback
Also, if we are interested in starting playback as soon as our widget is loaded and ready, we can use the following JavaScript code:
widget.bind(SC.Widget.Events.READY, function (eventData) { widget.play(); });This is ideal for demos, landing pages, or automatic players.
Updating the widget songs with the load function in JavaScript
Now, if we want to update the song at the end of the current song as if it were a playlist:
widget.load($($('.lista_canciones li')[index]).attr("data-href"), {auto_play: true});And we include it within our finish event:
widget.bind(SC.Widget.Events.FINISH, function (eventData) {
// to do
widget.load($($('.lista_canciones li')[index]).attr("data-href"), {auto_play: true});
});With this, we create the widget in our application with the provided URL.
Creating a dynamic playlist with SoundCloud
Once you have the events under control, the next logical step is to update the songs dynamically.
Loading new songs at the end of playback
SoundCloud offers the load method, which allows loading a new track in the same widget:
widget.load(
$($('.lista_canciones li')[index]).attr("data-href"),
{ auto_play: true }
);If we combine it with the FINISH event, we get a playlist-type behavior:
widget.bind(SC.Widget.Events.FINISH, function () {
widget.load(
$($('.lista_canciones li')[index]).attr("data-href"),
{ auto_play: true }
);
});This makes integrating content extremely simple.
Legal use of SoundCloud music in web applications
One of the biggest fears when working with music is the legal aspect. Here SoundCloud makes it easy:
- You use the official player
- You respect the platform's conditions
- You do not download or redistribute the audio
Common problems with the SoundCloud API and how to avoid them
Based on real questions from Reddit:
- 401 / 403 Errors → usually come from incorrect use of the SDK or lack of OAuth
- “I don't want to use login” → use the Widget API
- Little artist information → the Widget is for playback, not for data scraping
- The API has changed → many old tutorials are outdated
If your goal is to play music, don't overcomplicate the project.
Use of URLs in SoundCloud
As we see, we use a URL, which matches the URL of the song to be displayed or a group of songs; in our example, we specify a user's favorite songs:
- http://api.soundcloud.com/users/1539950/favorites
- But we can also specify individual songs:
- https://soundcloud.com/davidguetta/david-guetta-ft-sam-martin-dangerous-robin-schulz-remix-radio-edit
Individual song:
- https://soundcloud.com/davidguetta/david-guetta-ft-sam-martin-dangerous-robin-schulz-remix-radio-edit
With everything we have seen so far, it is more than enough to create our own basic player, loading/updating songs on demand or every time a song ends, in addition to a series of events that will allow us to further customize the interaction with the user.
FAQs
- Does the SoundCloud API need OAuth?
- Not always. The Widget API does not need it.
- Can SoundCloud be used without login?
- Yes, using the official embedded player.
- Is it legal to play SoundCloud music on my website?
- Yes, as long as you use their official widgets.
- Can I detect when a song ends?
- Yes, with the SC.Widget.Events.FINISH event.
Conclusion
With the SoundCloud API in JavaScript, and especially using the official Widget, you can create a complete, legal, and functional music player with very little code.
In my experience, combining:
- SC.Widget
- Events like READY and FINISH
- Dynamic loading of songs
It is more than enough to set up a personalized player without a backend, without OAuth, and without headaches.