How to Integrate Lovable with SoundCloud API

To use the SoundCloud API, you need a client_id from a registered SoundCloud app. The client_id identifies your application in API requests and is your authentication credential for public data access. Log in to SoundCloud at soundcloud.com. Navigate to soundcloud.com/you/apps (or go to your profile → Settings → scroll to find the developer apps section). Click 'Register a new application'. Fill in the app registration form: - App name: your Lovable app's name - App URI (Homepage): your Lovable app's deployed URL (e.g., https://myapp.lovable.app) - Redirect URI: your app's callback URL if you plan to implement user OAuth (e.g., https://myapp.lovable.app/soundcloud-callback). For public-only data access, this can be any URL. Click 'Save app'. SoundCloud will show your app's details including the Client ID. The Client ID is the credential you will store as a secret. Note that SoundCloud has historically had varying approval times and developer program availability — if app registration is unavailable, the oEmbed endpoint works without any credentials for embedded players. The client_id is somewhat sensitive — while it only provides access to public SoundCloud data, it can be rate-limited or revoked if abused. Keep it in Cloud → Secrets rather than hardcoding it.

Store your SoundCloud client_id in Lovable's Cloud Secrets panel. While the SoundCloud client_id only provides read access to public data (unlike database passwords or payment keys), keeping it server-side prevents rate limit issues from browser-side use and makes it easy to rotate if needed. In Lovable, click '+' next to the Preview label → Cloud panel → Secrets tab. Click 'Add new secret'. Name: SOUNDCLOUD_CLIENT_ID Value: your SoundCloud client_id Click Save. This single secret is all the credential configuration needed for public SoundCloud data access. If you later implement user OAuth for accessing private playlists and liked tracks, you will also add SOUNDCLOUD_CLIENT_SECRET. With the secret saved, your Edge Function will access it via Deno.env.get('SOUNDCLOUD_CLIENT_ID') and append it to all SoundCloud API requests.

Create the main Edge Function that proxies SoundCloud API calls. SoundCloud's REST API uses standard GET requests with the client_id appended as a query parameter (not as a header). The base URL for most API calls is https://api.soundcloud.com/. The track search endpoint is: GET https://api.soundcloud.com/tracks?q={query}&client_id={clientId}&limit={limit}&linked_partitioning=1. Additional filter parameters: genres, tags, bpm[from], bpm[to], duration[from], duration[to], filter (public, private, streamable, downloadable). SoundCloud track objects include: id, title, permalink_url, user (username and avatar_url), artwork_url, stream_url, playback_count, favoritings_count, duration (in milliseconds), tag_list, and genre. For audio playback, the stream_url from the API response requires the client_id appended: stream_url + '?client_id=' + clientId. Since the client_id should stay server-side, your Edge Function should either: (a) return a time-limited signed URL, or (b) proxy the audio stream itself. For most apps, returning the stream URL with the client_id appended is acceptable since the client_id only provides read access to public audio — but if you want maximum security, proxy the stream through the Edge Function. The function below shows the track search pattern. The URL resolve endpoint (GET https://api.soundcloud.com/resolve?url={soundcloud_url}&client_id={clientId}) is also demonstrated — it converts any public SoundCloud URL (profile URL, track URL, playlist URL) to its API representation.

1import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
2
3const corsHeaders = {
4  'Access-Control-Allow-Origin': '*',
5  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
6}
7
8serve(async (req) => {
9  if (req.method === 'OPTIONS') {
10    return new Response('ok', { headers: corsHeaders })
11  }
12
13  try {
14    const url = new URL(req.url)
15    const query = url.searchParams.get('q') || ''
16    const genre = url.searchParams.get('genre') || ''
17    const limit = parseInt(url.searchParams.get('limit') || '20', 10)
18
19    const clientId = Deno.env.get('SOUNDCLOUD_CLIENT_ID')
20    if (!clientId) {
21      throw new Error('SOUNDCLOUD_CLIENT_ID secret is not configured')
22    }
23
24    if (!query && !genre) {
25      return new Response(
26        JSON.stringify({ error: 'Provide at least a search query or genre' }),
27        { status: 400, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
28      )
29    }
30
31    const searchUrl = new URL('https://api.soundcloud.com/tracks')
32    if (query) searchUrl.searchParams.set('q', query)
33    if (genre) searchUrl.searchParams.set('genres', genre)
34    searchUrl.searchParams.set('client_id', clientId)
35    searchUrl.searchParams.set('limit', String(limit))
36    searchUrl.searchParams.set('linked_partitioning', '1')
37    searchUrl.searchParams.set('filter', 'public')
38
39    const response = await fetch(searchUrl.toString())
40
41    if (!response.ok) {
42      const error = await response.text()
43      throw new Error(`SoundCloud API error ${response.status}: ${error}`)
44    }
45
46    const data = await response.json()
47    const tracks = (data.collection || data).map((track: Record<string, unknown>) => ({
48      id: track.id,
49      title: track.title,
50      artist: (track.user as Record<string, string>)?.username || 'Unknown Artist',
51      artworkUrl: track.artwork_url
52        ? (track.artwork_url as string).replace('large', 't500x500')
53        : null,
54      duration: track.duration,  // milliseconds
55      playbackCount: track.playback_count,
56      permalinkUrl: track.permalink_url,
57      // Append client_id for streaming — client can play this URL directly
58      streamUrl: track.stream_url ? `${track.stream_url}?client_id=${clientId}` : null,
59    }))
60
61    return new Response(
62      JSON.stringify({ tracks, nextHref: data.next_href }),
63      { headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
64    )
65  } catch (error) {
66    return new Response(
67      JSON.stringify({ error: error.message }),
68      { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
69    )
70  }
71})

With the search Edge Function deployed, build the frontend components that display track results and play audio. SoundCloud's stream URLs work directly in HTML5 audio elements — use React's useRef to manage the audio element and control playback programmatically. The most important UI states to handle: loading (fetching search results), idle (no audio selected), playing (audio in progress), paused, and error (stream URL unavailable or track deleted). Use the HTML5 audio element's onEnded, onError, onPlay, onPause, and onTimeUpdate events to sync your React state with the actual audio playback state. For a polished player experience, show a waveform visualization or a simple progress bar using the audio element's currentTime and duration properties. Many audio apps use SoundCloud's waveform images (waveform_url in the API response) as visual placeholders — they are pre-rendered PNG images of each track's audio waveform. For building a podcast directory or music curation tool, pair the SoundCloud search Edge Function with a Supabase table that stores curated track IDs, editorial notes, and category tags. Your app presents a curated experience while the audio streams from SoundCloud's CDN.

1import { useState, useRef, useEffect } from 'react'
2import { supabase } from '@/lib/supabase'
3
4interface Track {
5  id: number
6  title: string
7  artist: string
8  artworkUrl: string | null
9  duration: number
10  streamUrl: string | null
11  permalinkUrl: string
12}
13
14export const useSoundCloudPlayer = () => {
15  const audioRef = useRef<HTMLAudioElement | null>(null)
16  const [currentTrack, setCurrentTrack] = useState<Track | null>(null)
17  const [isPlaying, setIsPlaying] = useState(false)
18  const [progress, setProgress] = useState(0)
19
20  useEffect(() => {
21    if (!audioRef.current) {
22      audioRef.current = new Audio()
23      audioRef.current.addEventListener('timeupdate', () => {
24        if (audioRef.current) {
25          setProgress(
26            (audioRef.current.currentTime / audioRef.current.duration) * 100 || 0
27          )
28        }
29      })
30      audioRef.current.addEventListener('ended', () => setIsPlaying(false))
31    }
32  }, [])
33
34  const play = (track: Track) => {
35    if (!track.streamUrl) return
36    if (audioRef.current) {
37      if (currentTrack?.id === track.id) {
38        isPlaying ? audioRef.current.pause() : audioRef.current.play()
39        setIsPlaying(!isPlaying)
40      } else {
41        audioRef.current.src = track.streamUrl
42        audioRef.current.play()
43        setCurrentTrack(track)
44        setIsPlaying(true)
45      }
46    }
47  }
48
49  return { currentTrack, isPlaying, progress, play }
50}