Musica code: parsers, embed iframes, SoundCloud only path

Nine parsers. One provider that didn’t fight the iframe.

---

Not a shipping music platform — see Musica: changelog & honesty for the plain-English correction. This file is engineering notes on what we wired; SoundCloud was the embed that behaved; other sites mostly taught us their lock-down model.

---

This post walks the code paths (URL normalization, buildEmbedTargetFromTrack, Audius stream JSON, Electron download IPC) that would power a real multi-provider player. Reality: those companies design their web audio to stay inside their own apps. We did not “fail to integrate Spotify”; we hit walls on purpose. Treat everything below as documentation of an experiment, not a roadmap promise.

---

The Multi-Provider Challenge

Platform Diversity

If you could build a unified in-app player across nine platforms, you would need to reconcile vastly different technical surfaces — but the harder problem is legal and product policy, not regex:

// URL structure variations across providers
const urlPatterns = {
  soundcloud: /soundcloud\.com\/([^\/]+)\/([^\/\?]+)/,
  youtube: /(?:youtube\.com\/watch\?v=|youtu\.be\/)([a-zA-Z0-9_-]{6,})/,
  spotify: /spotify\.com\/(track|album|playlist)\/([a-zA-Z0-9]+)/,
  audius: /audius\.co\/([^\/]+)\/([^\/\?]+)/,
  archive: /archive\.org\/details\/([^\/\?]+)/
}

Each provider has different:

• URL structures — From YouTube’s video IDs to Spotify’s URI format
• Embed capabilities — iframe support, autoplay policies, CORS restrictions
• API availability — Some offer public APIs, others require authentication
• Content policies — Different approaches to downloadable content and streaming

---

Provider Abstraction Layer

Unified URL Parsing System

The core challenge is normalizing diverse URL formats into a consistent internal representation:

class MusicaService {
  async parseSourceUrl(provider, url) {
    const parsers = {
      soundcloud: this.parseSoundCloudUrl,
      youtube: this.parseYouTubeUrl,
      spotify: this.parseSpotifyUrl,
      audius: this.parseAudiusUrl,
      // ... 5 more providers
    }
    
    const parser = parsers[provider] || this.parseSoundCloudUrl
    return await parser(url)
  }
}

Provider-Specific Implementation Examples

SoundCloud: User/Track Pattern

async parseSoundCloudUrl(url) {
  const urlMatch = url.match(/soundcloud\.com\/([^\/]+)\/([^\/\?]+)/)
  if (!urlMatch) return { success: false, error: 'Invalid SoundCloud URL' }
  
  const [, user, trackSlug] = urlMatch
  return {
    success: true,
    data: {
      provider: 'soundcloud',
      id: `soundcloud:${user}:${trackSlug}`,
      url,
      user,
      trackSlug,
      title: trackSlug.replace(/-/g, ' ').replace(/\b\w/g, l => l.toUpperCase()),
      artist: user.replace(/-/g, ' ').replace(/\b\w/g, l => l.toUpperCase())
    }
  }
}

YouTube: Multiple URL Formats

async parseYouTubeUrl(url) {
  let videoId = null
  
  // Handle multiple YouTube URL formats
  try {
    const urlObj = new URL(url)
    if (urlObj.hostname.includes('youtu.be')) {
      videoId = urlObj.pathname.replace('/', '')
    } else {
      videoId = urlObj.searchParams.get('v')
    }
  } catch {
    // Fallback regex parsing for malformed URLs
    const patterns = [
      /[?&]v=([a-zA-Z0-9_-]{6,})/,
      /youtu\.be\/([a-zA-Z0-9_-]{6,})/
    ]
    for (const pattern of patterns) {
      const match = url.match(pattern)
      if (match) {
        videoId = match[1]
        break
      }
    }
  }
  
  return videoId ? {
    success: true,
    data: { provider: 'youtube', id: `youtube:${videoId}`, videoId }
  } : { success: false, error: 'Could not parse YouTube URL' }
}

Audius: Path Normalization

async parseAudiusUrl(url) {
  // Audius URLs can be inconsistent: /user/track or /user//user/track
  let pathname = ''
  try {
    pathname = new URL(url).pathname
  } catch {
    const match = url.match(/audius\.co(\/[^?#]+)/)
    pathname = match?.[1] || ''
  }
  
  const parts = pathname.split('/').filter(Boolean)
  if (parts.length < 2) return { success: false, error: 'Invalid Audius URL' }
  
  // Handle inconsistent paths by using first and last segments
  const user = parts[0]
  const slug = parts[parts.length - 1]
  
  return {
    success: true,
    data: {
      provider: 'audius',
      id: `audius:${user}:${slug}`,
      url: `https://audius.co/${user}/${slug}`, // Normalize to canonical form
      audiusPath: `/${user}/${slug}`
    }
  }
}

---

Embed System Architecture

Provider-Specific Embed Patterns

Each streaming platform requires different embed approaches:

const EmbedRenderer = ({ embedTarget }) => {
  if (!embedTarget) return null
  
  const renderByProvider = {
    youtube: () => (
      <iframe
        width="100%" height="315"
        src={`https://www.youtube.com/embed/${embedTarget.videoId}?autoplay=1&enablejsapi=1`}
        allow="accelerometer; autoplay; clipboard-write; encrypted-media"
        allowFullScreen
      />
    ),
    
    soundcloud: () => (
      <iframe
        width="100%" height="166"
        src={`https://w.soundcloud.com/player/?url=${encodeURIComponent(embedTarget.url)}&auto_play=true`}
        allow="autoplay"
        scrolling="no"
        frameBorder="no"
      />
    ),
    
    spotify: () => (
      <iframe
        width="100%" height="152"
        src={`https://open.spotify.com/embed/${embedTarget.spotifyType}/${embedTarget.spotifyId}`}
        allow="autoplay; clipboard-write; encrypted-media; fullscreen"
      />
    ),
    
    audius: () => {
      const embedPath = embedTarget.audiusPath
      return embedPath ? (
        <iframe
          width="100%" height="160"
          src={`https://audius.co/embed${embedPath}`}
          allow="autoplay"
        />
      ) : <div>Could not load Audius player</div>
    }
  }
  
  return renderByProvider[embedTarget.provider]?.() || null
}

Embed Target Builder

The system uses a builder pattern to create provider-appropriate embed configurations:

function buildEmbedTargetFromTrack(track) {
  if (!track || typeof track !== 'object') return null

  return {
    provider: track.provider || 'soundcloud',
    url: track.url,
    
    // Provider-specific identifiers preserved from parsing
    videoId: track.videoId,           // YouTube
    spotifyType: track.spotifyType,   // Spotify (track/album/playlist)
    spotifyId: track.spotifyId,       // Spotify ID
    applePath: track.applePath,       // Apple Music path
    deezerType: track.deezerType,     // Deezer type
    deezerId: track.deezerId,         // Deezer ID
    mixcloudFeed: track.mixcloudFeed, // Mixcloud feed path
    vimeoId: track.vimeoId,           // Vimeo video ID
    archiveId: track.archiveId,       // Internet Archive identifier
    audiusPath: track.audiusPath      // Audius canonical path
  }
}

---

Search Architecture: Multi-Source Federation

Browser-First API Strategy

The search system prioritizes CORS-friendly endpoints while providing fallbacks:

class MusicaSearchService {
  async searchAudius(query, limit = 8) {
    // Direct API call to public Audius discovery provider
    const url = `https://discoveryprovider.audius.co/v1/tracks/search?query=${encodeURIComponent(query)}&limit=${limit}`
    
    try {
      const response = await fetch(url)
      if (!response.ok) throw new Error(`HTTP ${response.status}`)
      
      const json = await response.json()
      return {
        success: true,
        data: this.normalizeAudiusResults(json.data || [])
      }
    } catch (error) {
      return { success: false, error: error.message }
    }
  }
  
  // For providers with API restrictions, generate search URLs
  buildProviderSearchUrl(provider, query) {
    const searchUrls = {
      spotify: `https://open.spotify.com/search/${encodeURIComponent(query)}`,
      applemusic: `https://music.apple.com/us/search?term=${encodeURIComponent(query)}`,
      youtube: `https://www.youtube.com/results?search_query=${encodeURIComponent(query)}`
    }
    
    return searchUrls[provider] || ''
  }
}

Audius Permalink Normalization

Audius API responses often contain inconsistent URL formats requiring normalization:

normalizeAudiusPermalink(permalinkUrl, handle, permalink) {
  const safeHandle = (handle || '').trim().replace(/^\/+|\/+$/g, '')
  let safePermalink = (permalink || '').trim().replace(/^\/+|\/+$/g, '')
  
  // Handle path-like permalinks (e.g., "handle/track-slug")
  if (safePermalink.includes('/')) {
    const slugParts = safePermalink.split('/').filter(Boolean)
    safePermalink = slugParts[slugParts.length - 1] || safePermalink
  }
  
  // Construct canonical URL
  if (safeHandle && safePermalink) {
    return {
      url: `https://audius.co/${safeHandle}/${safePermalink}`,
      path: `/${safeHandle}/${safePermalink}`,
      handle: safeHandle,
      slug: safePermalink
    }
  }
  
  // Fallback parsing for malformed URLs
  return this.parsePermalinkUrl(permalinkUrl, safeHandle, safePermalink)
}

---

Dual Playback System Architecture

Embedded vs. Direct Playback Decision Tree

The app uses a sophisticated playback routing system:

const handlePlayTrack = async (track) => {
  // Decision tree for playback method
  if (track.filePath) {
    // Local downloaded file - use HTML5 audio
    return await playLocalFile(track)
  }
  
  if (track.provider === 'audius' && track.audiusTrackId) {
    // Audius direct streaming (bypasses embed for better Electron compatibility)
    try {
      const streamUrl = await musicaService.getAudiusStreamUrl(track.audiusTrackId)
      if (streamUrl.success) {
        return await playDirectStream(streamUrl.data.url, track)
      }
    } catch (error) {
      console.warn('Audius direct stream failed, falling back to embed:', error)
    }
  }
  
  // Default: embedded player
  return playViaEmbed(track)
}

Audius Direct Streaming Implementation

Audius offers a unique capability for direct MP3 streaming bypassing embeds:

async getAudiusStreamUrl(trackId) {
  try {
    const url = `https://discoveryprovider.audius.co/v1/tracks/${encodeURIComponent(trackId)}/stream?app_name=gato&no_redirect=true`
    
    const response = await fetch(url)
    if (!response.ok) return { success: false, error: `HTTP ${response.status}` }
    
    const json = await response.json()
    const streamUrl = json?.data?.url
    
    if (typeof streamUrl !== 'string' || !streamUrl) {
      return { success: false, error: 'Stream URL missing from response' }
    }
    
    return { success: true, data: { url: streamUrl } }
  } catch (error) {
    return { success: false, error: error.message }
  }
}

Local File Playback (Electron)

Downloaded SoundCloud tracks use native HTML5 audio:

const playLocalFile = async (track) => {
  if (typeof window !== 'undefined' && window.electronAPI) {
    // Electron: convert file path to file:// URL  
    const result = await window.electronAPI.getFileUrl(track.filePath)
    if (result.success) {
      audioRef.current.src = result.data.url
      audioRef.current.play()
      return { success: true, mode: 'local' }
    }
  } else {
    // Browser: direct file path (limited compatibility)
    audioRef.current.src = track.filePath
    audioRef.current.play()
    return { success: true, mode: 'browser-local' }
  }
}

---

Storage Architecture and Migration Strategy

Microservice-Ready Data Layer

All persistence flows through a unified service abstraction:

// High-level service call
const result = await musicaService.savePlaylist(id, name, tracks)

// Translates to storage service
const storageResult = await storageService.saveMusicaPlaylist(id, name, tracks)

// Which calls the backend abstraction
const backendResult = await storageBackend.setItem('MUSICA_PLAYLISTS', id, {
  id, name, tracks,
  createdAt: existingPlaylist?.createdAt || new Date().toISOString(),
  updatedAt: new Date().toISOString()
})

Backend Selection Logic

The storage backend adapts to the runtime environment:

// In storageBackend.js
const getBackend = () => {
  if (typeof window !== 'undefined' && window.electronAPI) {
    return electronBackend  // PostgreSQL via IPC
  } else {
    return localStorageBackend  // Browser localStorage
  }
}

export const storageBackend = getBackend()

API Migration Path

The architecture enables seamless API migration:

// Current: Local storage backend
class LocalStorageBackend {
  async getItem(collection, id) {
    const data = localStorage.getItem(`gato${collection}`)
    return JSON.parse(data || '{}')[id] || null
  }
}

// Future: API backend (same interface)
class ApiBackend {
  async getItem(collection, id) {
    const response = await fetch(`/api/v1/${collection}/${id}`)
    return await response.json()
  }
}

---

Cross-Origin and Security Considerations

CORS Handling Strategy

Different providers have different CORS policies:

const corsCompatibility = {
  audius: 'full-api',        // Public API with CORS headers
  archive: 'full-api',       // JSON API with CORS support  
  soundcloud: 'embed-only',  // No CORS, embed iframe only
  youtube: 'embed-only',     // No CORS, embed iframe only
  spotify: 'embed-only'      // Requires OAuth, embed only
}

Content Security Policy (CSP)

The app handles CSP restrictions, especially in Electron:

// CSP-safe embed detection
const isEmbedBlocked = (provider) => {
  // Audius embeds are blocked by CSP in Electron
  if (provider === 'audius' && typeof window !== 'undefined' && window.electronAPI) {
    return true
  }
  return false
}

// Fallback to direct streaming when embeds are blocked
if (isEmbedBlocked(track.provider)) {
  return await useDirectStreaming(track)
}

---

Performance and Optimization

Lazy Loading and Resource Management

// Embedded players are only rendered when needed
const EmbedPlayer = ({ embedTarget, isActive }) => {
  if (!isActive) return <div className="embed-placeholder">Click to load player</div>
  
  return <iframe src={buildEmbedUrl(embedTarget)} />
}

Memory Management for Large Playlists

// Virtualized playlist rendering for performance
const PlaylistView = ({ tracks }) => {
  const [visibleRange, setVisibleRange] = useState({ start: 0, end: 50 })
  
  return (
    <VirtualizedList
      items={tracks}
      renderItem={({ item }) => <TrackCard track={item} />}
      visibleRange={visibleRange}
      onRangeChange={setVisibleRange}
    />
  )
}

---

Error Handling and Resilience

Graceful Provider Degradation

const handleProviderError = (provider, error) => {
  const fallbackStrategies = {
    'network-error': () => showOfflineMode(),
    'embed-blocked': () => showDirectLinkFallback(),
    'api-rate-limit': () => showSearchUrlFallback(provider),
    'invalid-url': () => showUrlValidationError()
  }
  
  const errorType = classifyError(error)
  const fallback = fallbackStrategies[errorType]
  
  if (fallback) {
    fallback()
  } else {
    showGenericError(error)
  }
}

---

Future Architecture Considerations

Microservice Migration Timeline

The current architecture enables a phased migration:

1. Phase 1: Replace storage backend with API client
2. Phase 2: Move search aggregation to dedicated service
3. Phase 3: Implement real-time playlist synchronization
4. Phase 4: Add collaborative playlist features

Extensibility for New Providers

Adding new streaming providers requires implementing three interfaces:

interface ProviderAdapter {
  parseUrl(url: string): Promise<TrackMetadata>
  buildEmbedTarget(metadata: TrackMetadata): EmbedTarget
  searchTracks?(query: string): Promise<TrackMetadata[]>
}

---

Summary

The Musica preview’s code stages parsers and embed builders the way you would if you expected partners to allow playback. Reality: partners mostly don’t. SoundCloud was the one iframe path that felt honest in daily use; the rest is documentation of what we tried and why it hurt.

URL normalization and { success, data, error } services are still a fine pattern for real Vault apps. They do not turn Musica into a streaming product until there is licensed API access or owned audio.

Clean TypeScript. Hostile embed policies. Lessons cheap at twice the price.

---

Technical Sources: src/apps/musica/services/musicaService.js, src/apps/musica/services/musicaSearchService.js, src/apps/musica/utils/embedTarget.js, src/services/storageService.js, and streaming platform API documentation.