How to Integrate Bolt.new with SoundCloud API

Before writing any code, take a moment to understand what is and is not possible with SoundCloud in 2026. This will save you time and prevent frustration from pursuing paths that do not work. SoundCloud's developer API (the API that allowed searching tracks, getting user libraries, accessing waveform data, and controlling streaming) was closed to new registrations in 2017. The suspension has never been lifted. If you search GitHub for SoundCloud API libraries and find Python or Node.js packages that claim to provide full API access, these libraries exploit unofficial internal endpoints discovered through reverse engineering. These endpoints are not documented, not officially supported, and can be blocked or changed at any time without notice. Using them violates SoundCloud's Terms of Service. Multiple popular SoundCloud scraping libraries have been broken overnight when SoundCloud updated their internal authentication. Here is exactly what does work legitimately in 2026. The oEmbed endpoint is an international standard for embedding content across platforms. SoundCloud maintains a public oEmbed endpoint at https://soundcloud.com/oembed that accepts any public SoundCloud URL and returns JSON with an html field containing an iframe embed code. No authentication is required. This works for any public track or playlist URL. Limitation: you must already know the track URL — this is not a search endpoint. The Widget API is a JavaScript library at https://w.soundcloud.com/player/api.js that lets you interact with a SoundCloud embedded player. Once a track is embedded as an iframe using the standard SoundCloud embed URL format (https://w.soundcloud.com/player/?url=TRACK_URL), the Widget API lets you call play(), pause(), seekTo(), and listen to events like PLAY, PAUSE, PLAY_PROGRESS, and FINISH. This enables building custom player UIs around the embedded SoundCloud player. If your use case requires any of the following, SoundCloud's available paths will not work and you need Spotify: searching for tracks by keyword, fetching a user's liked tracks or follows, accessing audio features or waveform data, discovering related tracks, building a music recommendation engine, or allowing users to log in with their SoundCloud account. Decide now which path fits your use case. If you have specific track URLs and just need to embed players, proceed with this guide. If you need any discovery or user data features, jump to the Spotify alternative section at the end.

The SoundCloud oEmbed endpoint is the most reliable way to embed SoundCloud audio in a Bolt.new app. It is maintained by SoundCloud as a standard feature, requires no authentication, and works for any public SoundCloud track, playlist, or set URL. The oEmbed endpoint is: GET https://soundcloud.com/oembed. It accepts these query parameters: url (required — the SoundCloud content URL, URL-encoded), format (json or xml — use json), auto_play (true or false), hide_related (true or false), show_comments (true or false), show_user (true or false), show_reposts (true or false), color (hex color without # for the player color). The response JSON contains: html (the complete iframe embed code), width, height, title, description, thumbnail_url, and author_name. In Bolt.new, calling oEmbed directly from a React component would cause CORS errors because the SoundCloud oEmbed endpoint does not include CORS headers for arbitrary origins. The solution is to create a Next.js API route that proxies the oEmbed request — the API route runs server-side where CORS restrictions do not apply. Create the API route at app/api/soundcloud/oembed/route.ts. It accepts a 'url' query parameter, calls the SoundCloud oEmbed endpoint with that URL, and returns the JSON response. In your React component, call /api/soundcloud/oembed?url=ENCODED_TRACK_URL to get the embed code, then render it using dangerouslySetInnerHTML. Note that dangerouslySetInnerHTML is safe here because the HTML comes from SoundCloud (a trusted source), not from user input. Bolt's WebContainer handles outbound HTTPS calls from API routes perfectly — you will see the embedded SoundCloud player in the Bolt preview as soon as you add a real SoundCloud track URL.

1// app/api/soundcloud/oembed/route.ts
2import { NextResponse } from 'next/server';
3
4interface OEmbedResponse {
5  html: string;
6  title: string;
7  description: string;
8  thumbnail_url: string;
9  author_name: string;
10  width: number;
11  height: number;
12}
13
14export async function GET(request: Request) {
15  const { searchParams } = new URL(request.url);
16  const trackUrl = searchParams.get('url');
17
18  if (!trackUrl) {
19    return NextResponse.json({ error: 'url parameter is required' }, { status: 400 });
20  }
21
22  // Validate it looks like a SoundCloud URL
23  if (!trackUrl.includes('soundcloud.com')) {
24    return NextResponse.json({ error: 'Invalid SoundCloud URL' }, { status: 400 });
25  }
26
27  try {
28    const oembedUrl = new URL('https://soundcloud.com/oembed');
29    oembedUrl.searchParams.set('url', trackUrl);
30    oembedUrl.searchParams.set('format', 'json');
31    oembedUrl.searchParams.set('auto_play', 'false');
32    oembedUrl.searchParams.set('show_user', 'true');
33    oembedUrl.searchParams.set('show_comments', 'false');
34    oembedUrl.searchParams.set('hide_related', 'true');
35
36    const res = await fetch(oembedUrl.toString());
37    if (!res.ok) {
38      return NextResponse.json({ error: 'Track not found or not public' }, { status: 404 });
39    }
40
41    const data: OEmbedResponse = await res.json();
42    return NextResponse.json({
43      html: data.html,
44      title: data.title,
45      author: data.author_name,
46      thumbnail: data.thumbnail_url,
47    });
48  } catch (error) {
49    return NextResponse.json({ error: 'Failed to fetch embed data' }, { status: 500 });
50  }
51}

For a more custom music player experience, SoundCloud's Widget API gives you JavaScript control over an embedded player. Instead of just showing the default SoundCloud iframe player, you can build your own play/pause button, seek bar, time display, and volume control while the embedded iframe handles the actual audio streaming. The Widget API is loaded as a script from https://w.soundcloud.com/player/api.js. It provides a SC.Widget(iframeElement) constructor that returns a widget object. The widget object has methods: play(), pause(), seekTo(milliseconds), setVolume(0-1), and getPosition(callback). It also supports event binding via widget.bind(SC.Widget.Events.EVENT_NAME, callback). The key events are READY (widget is loaded and ready), PLAY, PAUSE, PLAY_PROGRESS (fires periodically with current position), and FINISH. Binding to PLAY_PROGRESS lets you update a custom seek bar position as the track plays. Binding to READY lets you call getDuration() to get the total track length for displaying remaining time. In the React component, use a ref to hold the iframe element and another ref for the widget object (not state, since we do not want React to re-render when the widget updates position). Create play/pause toggle state that calls widget.play() or widget.pause(). Use a useEffect cleanup to unbind all event listeners when the component unmounts to prevent memory leaks. Note: The Widget API requires the iframe src to use the SoundCloud player URL format (https://w.soundcloud.com/player/?url=ENCODED_TRACK_URL) rather than the standard soundcloud.com track URL. This is different from the oEmbed approach — here you construct the iframe src manually rather than using the HTML returned by oEmbed.

1// components/SoundCloudWidget.tsx
2'use client';
3import { useEffect, useRef, useState } from 'react';
4
5// Type declarations for SoundCloud Widget API
6declare global {
7  interface Window {
8    SC?: {
9      Widget: ((iframe: HTMLIFrameElement) => SCWidget) & {
10        Events: { READY: string; PLAY: string; PAUSE: string; PLAY_PROGRESS: string; FINISH: string };
11      };
12    };
13  }
14}
15
16interface SCWidget {
17  play: () => void;
18  pause: () => void;
19  seekTo: (ms: number) => void;
20  getPosition: (cb: (position: number) => void) => void;
21  getDuration: (cb: (duration: number) => void) => void;
22  bind: (event: string, cb: (data?: { currentPosition?: number }) => void) => void;
23  unbind: (event: string) => void;
24}
25
26function formatTime(ms: number): string {
27  const secs = Math.floor(ms / 1000);
28  return `${Math.floor(secs / 60)}:${String(secs % 60).padStart(2, '0')}`;
29}
30
31export function SoundCloudWidget({ trackUrl }: { trackUrl: string }) {
32  const iframeRef = useRef<HTMLIFrameElement>(null);
33  const widgetRef = useRef<SCWidget | null>(null);
34  const [isPlaying, setIsPlaying] = useState(false);
35  const [currentTime, setCurrentTime] = useState(0);
36  const [duration, setDuration] = useState(0);
37
38  const embedUrl = `https://w.soundcloud.com/player/?url=${encodeURIComponent(trackUrl)}&auto_play=false&hide_related=true&show_comments=false&show_user=true`;
39
40  useEffect(() => {
41    if (!document.getElementById('sc-widget-script')) {
42      const script = document.createElement('script');
43      script.id = 'sc-widget-script';
44      script.src = 'https://w.soundcloud.com/player/api.js';
45      script.async = true;
46      script.onload = () => initWidget();
47      document.head.appendChild(script);
48    } else {
49      // Give iframe time to load before initializing
50      setTimeout(() => initWidget(), 500);
51    }
52
53    function initWidget() {
54      if (!iframeRef.current || !window.SC) return;
55      const widget = window.SC.Widget(iframeRef.current);
56      widgetRef.current = widget;
57
58      widget.bind(window.SC.Widget.Events.READY, () => {
59        widget.getDuration((dur) => setDuration(dur));
60      });
61      widget.bind(window.SC.Widget.Events.PLAY, () => setIsPlaying(true));
62      widget.bind(window.SC.Widget.Events.PAUSE, () => setIsPlaying(false));
63      widget.bind(window.SC.Widget.Events.FINISH, () => setIsPlaying(false));
64      widget.bind(window.SC.Widget.Events.PLAY_PROGRESS, (data) => {
65        if (data?.currentPosition !== undefined) setCurrentTime(data.currentPosition);
66      });
67    }
68
69    return () => {
70      if (widgetRef.current && window.SC) {
71        Object.values(window.SC.Widget.Events).forEach((e) => widgetRef.current?.unbind(e));
72      }
73    };
74  }, [trackUrl]);
75
76  return (
77    <div className="rounded-xl overflow-hidden border">
78      <iframe ref={iframeRef} src={embedUrl} width="100%" height="166"
79        allow="autoplay" className="block" />
80      <div className="flex items-center gap-3 bg-gray-900 p-3">
81        <button onClick={() => isPlaying ? widgetRef.current?.pause() : widgetRef.current?.play()}
82          className="rounded-full bg-orange-500 p-2 text-white hover:bg-orange-600">
83          {isPlaying ? '⏸' : '▶'}
84        </button>
85        <span className="font-mono text-sm text-gray-300">
86          {formatTime(currentTime)} / {formatTime(duration)}
87        </span>
88      </div>
89    </div>
90  );
91}

If your use case requires search, discovery, user libraries, or any feature beyond embedding specific known tracks, the Spotify Web API is the right choice. Spotify has an active developer program, comprehensive documentation, officially maintained SDKs, and a generous free tier that works for development and small-scale production apps. To get started with Spotify, go to developer.spotify.com/dashboard and log in with a Spotify account. Click 'Create App.' Fill in the app name, description, and redirect URI (use http://localhost:3000/api/auth/callback/spotify for development). Accept the Developer Terms and click Save. On the app page, click 'Settings' to see your Client ID and Client Secret. Spotify's API uses OAuth 2.0 with two common flows: the Client Credentials Flow (server-to-server, no user login required, works for searching public content) and the Authorization Code Flow (requires user login, works for accessing user playlists, liked songs, and playback control). For building a public music search and discovery feature, Client Credentials is sufficient. For building a personalized player or playlist manager, you need Authorization Code. In Bolt.new, create a Next.js API route that uses the Client Credentials flow: POST to https://accounts.spotify.com/api/token with your client credentials to get an access token, then use that token to call Spotify's search endpoint (GET /v1/search?q=QUERY&type=track). The access token expires after 3600 seconds, so implement the same caching pattern used in the CoStar guide. Spotify also provides web playback through the Spotify Web Playback SDK — a JavaScript library that turns any browser into a Spotify streaming device. This requires user authentication (Authorization Code flow) and a Spotify Premium account on the user's side, but it enables true in-browser audio streaming without opening the Spotify app.

1// lib/spotify.ts
2// Full-featured alternative to SoundCloud for music search and discovery
3const SPOTIFY_BASE = 'https://api.spotify.com/v1';
4const TOKEN_URL = 'https://accounts.spotify.com/api/token';
5
6interface TokenCache { token: string; expiresAt: number; }
7let tokenCache: TokenCache | null = null;
8
9export async function getSpotifyToken(): Promise<string> {
10  if (tokenCache && tokenCache.expiresAt > Date.now() + 60_000) {
11    return tokenCache.token;
12  }
13  const clientId = process.env.SPOTIFY_CLIENT_ID;
14  const clientSecret = process.env.SPOTIFY_CLIENT_SECRET;
15  if (!clientId || !clientSecret) throw new Error('Spotify credentials not configured');
16
17  const res = await fetch(TOKEN_URL, {
18    method: 'POST',
19    headers: {
20      'Content-Type': 'application/x-www-form-urlencoded',
21      Authorization: `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString('base64')}`,
22    },
23    body: 'grant_type=client_credentials',
24  });
25  if (!res.ok) throw new Error(`Spotify token error: ${res.status}`);
26  const data = await res.json();
27  tokenCache = { token: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 };
28  return tokenCache.token;
29}
30
31export async function searchTracks(query: string, limit = 10) {
32  const token = await getSpotifyToken();
33  const params = new URLSearchParams({ q: query, type: 'track', limit: String(limit) });
34  const res = await fetch(`${SPOTIFY_BASE}/search?${params}`, {
35    headers: { Authorization: `Bearer ${token}` },
36  });
37  if (!res.ok) throw new Error(`Spotify search error: ${res.status}`);
38  const data = await res.json();
39  return data.tracks.items.map((t: {
40    id: string; name: string;
41    artists: Array<{ name: string }>;
42    album: { name: string; images: Array<{ url: string }> };
43    preview_url: string | null;
44    external_urls: { spotify: string };
45    duration_ms: number;
46  }) => ({
47    id: t.id,
48    name: t.name,
49    artists: t.artists.map((a) => a.name).join(', '),
50    albumName: t.album.name,
51    albumImageUrl: t.album.images[0]?.url ?? '',
52    previewUrl: t.preview_url,
53    spotifyUrl: t.external_urls.spotify,
54    durationMs: t.duration_ms,
55  }));
56}