Suno

pnpm add @joycostudio/suno

import { Suno } from '@joycostudio/suno'
 
const suno = new Suno({
  manifest: {
    click: { src: '/audio/click.ogg' },
    ambient: { src: '/audio/ambient.ogg', loop: true, volume: 0.6 },
  },
})
 
// Must be called from a user gesture (browser policy)
await suno.unlock()
await suno.loadAll()
 
suno.get('click').play()
suno.get('ambient').play({ loop: true })

import { SunoProvider, useSuno, useUnlock } from '@joycostudio/suno/react'
 
const MANIFEST = {
  click: { src: '/audio/click.ogg' },
  ambient: { src: '/audio/ambient.ogg', loop: true, volume: 0.6 },
} as const
 
function App() {
  return (
    <SunoProvider manifest={MANIFEST}>
      <AudioUI />
    </SunoProvider>
  )
}
 
function AudioUI() {
  const suno = useSuno<typeof MANIFEST>()
  const { unlock, unlocked } = useUnlock()
 
  const start = async () => {
    await unlock()
    await suno.loadAll()
  }
 
  return (
    <div>
      {!unlocked && <button onClick={start}>Start audio</button>}
      <button onClick={() => suno.get('click').play()}>Click</button>
    </div>
  )
}

type AudioAssetDefinition = {
  src: string // URL to the audio file
  loop?: boolean // Default loop setting (default: false)
  volume?: number // Default voice volume (default: 1)
}
 
type AudioManifest = Record<string, AudioAssetDefinition>

const MANIFEST = {
  'hero-ambient': { src: '/audio/hero-ambient.ogg', loop: true, volume: 0.6 },
  alert: { src: '/audio/alert.ogg' },
} as const
 
const suno = new Suno({ manifest: MANIFEST })
await suno.loadAll()
 
// Typed — TS knows valid keys
suno.get('hero-ambient').play()

import { Suno } from '@joycostudio/suno'
 
const suno = new Suno(options?: SunoOptions)

type SunoOptions<M extends AudioManifest = AudioManifest> = {
  manifest?: M // Pre-register assets
  player?: WebAudioPlayer // Share a player across instances
}

// Chain effect nodes and connect to master output.
// Returns the head node — pass it as play({ output }).
const fx = suno.effect(filter, reverb)
 
suno.get('click').play({ output: fx })

type SunoEventMap = {
  load: { key: string; source: AudioSource }
  unload: { key: string }
  voicestart: { key: string; source: AudioSource; voice: Voice }
  voiceend: { key: string; source: AudioSource; voice: Voice }
  voicechange: { key: string; source: AudioSource; voice: Voice; type: keyof VoiceEventMap }
  playingchange: { playing: ReadonlyArray<PlayingVoice> }
}
 
const unsub = suno.on('voicestart', ({ key, voice }) => {
  console.log(`${key} started playing`)
})
 
// Call unsub() to remove the listener

await suno.dispose() // Stops everything, closes AudioContext

const voice = source.play(opts?: PlayOptions)

type PlayOptions = {
  volume?: number // Initial voice volume (default: source default)
  loop?: boolean // Loop this voice (default: source default)
  exclusive?: boolean // Stop existing voices on this source first
  playbackRate?: number // Local rate (default: 1)
  output?: AudioNode // Override output (default: source's outputNode)
}

type AudioSourceEventMap = {
  voicestart: { source: AudioSource; voice: Voice }
  voiceend: { source: AudioSource; voice: Voice }
  voicechange: { source: AudioSource; voice: Voice; type: keyof VoiceEventMap }
  volumechange: { source: AudioSource; volume: number }
}

type VoiceEventMap = {
  play: { voice: Voice }
  pause: { voice: Voice; at: number }
  stop: { voice: Voice }
  ended: { voice: Voice } // Natural end (non-looping)
  volumechange: { voice: Voice; volume: number }
  loopchange: { voice: Voice; loop: boolean }
  playbackratechange: { voice: Voice; rate: number }
  statechange: { voice: Voice; state: VoicePlaybackState }
}

import { Mixer } from '@joycostudio/suno'
 
const mixer = new Mixer({
  suno,
  fadeOutDuration: 0.5, // seconds (default)
  fadeInDuration: 0, // seconds (default: instant)
  autoRaf: true, // run its own RAF loop (default: false)
})

// In your game/animation loop
function tick(delta: number) {
  mixer.update(delta) // delta in seconds
}

type MixerEventMap = {
  play: { key: string; voice: Voice }
  stop: { key: string; voice: Voice }
  fadestart: { key: string; voice: Voice; direction: 'in' | 'out' }
  fadeend: { key: string; voice: Voice; direction: 'in' | 'out' }
  update: { delta: number }
}

import { WebAudioPlayer } from '@joycostudio/suno'
 
const player = new WebAudioPlayer()
 
player.audioContext // Lazily creates AudioContext
player.masterOutput // Master GainNode
player.state // 'running' | 'suspended' | 'closed'
player.isPlaying // true if 'running'
 
await player.unlock()
player.setMasterVolume(0.8)
player.getMasterVolume()
 
await player.pause()
await player.resume()
await player.dispose()

// All classes (Suno, AudioSource, Voice, Mixer) extend this.
// Consistent API across all emitters:
 
const unsub = emitter.on('event', (payload) => { ... })  // Returns unsubscribe fn
emitter.once('event', (payload) => { ... })
emitter.off('event', listener?)                          // Remove specific or all

import {
  SunoProvider,
  useSuno,
  useUnlock,
  useSource,
  useVoice,
  usePlaying,
  useSunoState,
  Mixer,
} from '@joycostudio/suno/react'

// Self-managed: provider creates and disposes on unmount
<SunoProvider manifest={MANIFEST}>
  {children}
</SunoProvider>
 
// Controlled: you own the instance
const suno = new Suno({ manifest: MANIFEST })
<SunoProvider value={suno}>
  {children}
</SunoProvider>

const suno = useSuno<typeof MANIFEST>()
// Typed — suno.get('known-key') is type-checked

const { unlock, unlocked } = useUnlock()
 
// Call from a user gesture handler
<button onClick={unlock}>Start</button>

type SourceState = {
  source: AudioSource
  isPlaying: boolean
  voices: ReadonlyArray<Voice>
  volume: number
  loop: boolean
  duration: number
}
 
const state = useSource('ambient')
// state is null until suno.load('ambient') resolves

type VoiceState = {
  state: VoicePlaybackState
  isPlaying: boolean
  currentTime: number
  duration: number
  volume: number
  loop: boolean
  playbackRate: number
  effectivePlaybackRate: number
}
 
const state = useVoice(voice)

const playing = usePlaying()
// ReadonlyArray<PlayingVoice>
// Each entry: { key, definition, source, voice }

type SunoState = {
  state: AudioPlayerState // 'running' | 'suspended' | 'closed'
  isPlaying: boolean
  masterVolume: number
  playbackRate: number
  unlocked: boolean
}
 
const state = useSunoState()

const snapshot = useEmitterSnapshot(
  source, // emitter instance (or null)
  ['voicestart', 'voiceend'], // events to listen for
  (s) => ({ playing: s.isPlaying }), // derive snapshot
  { playing: false } // fallback when null
)

const ctx = suno.player.audioContext
 
const filter = ctx.createBiquadFilter()
filter.type = 'lowpass'
filter.frequency.value = 2000
 
const fx = suno.effect(filter)
 
suno.get('ambient').play({ output: fx })
suno.get('click').play({ output: fx })
 
// Tweak live
filter.frequency.value = 800

const sfxBus = ctx.createGain()
sfxBus.connect(suno.player.masterOutput)
 
suno.get('click').play({ output: sfxBus })
suno.get('alert').play({ output: sfxBus })
 
// Duck all SFX at once
sfxBus.gain.value = 0.3

const mixer = new Mixer({ suno, fadeOutDuration: 1 })
 
function gameLoop(timestamp: number) {
  const delta = (timestamp - lastTime) / 1000
  lastTime = timestamp
 
  mixer.update(delta)
  // ... rest of game logic
 
  requestAnimationFrame(gameLoop)
}
requestAnimationFrame(gameLoop)

function AudioUI() {
  const suno = useSuno()
  const mixerRef = useRef<Mixer | null>(null)
  if (!mixerRef.current) mixerRef.current = new Mixer({ suno })
  const mixer = mixerRef.current
 
  useEffect(() => {
    let rafId: number
    let last = performance.now()
    const tick = (now: number) => {
      mixer.update((now - last) / 1000)
      last = now
      rafId = requestAnimationFrame(tick)
    }
    rafId = requestAnimationFrame(tick)
    return () => {
      cancelAnimationFrame(rafId)
      mixer.stopAll({ fadeOut: 0 })
      mixer.dispose()
    }
  }, [mixer])
 
  return (
    <>
      <button onClick={() => mixer.play('click')}>Play</button>
      <button onClick={() => mixer.stopAll()}>Fade out all</button>
    </>
  )
}

// Register and load in one call (no manifest needed)
await suno.load('boss-music', { src: '/audio/boss.ogg', loop: true, volume: 0.8 })
suno.get('boss-music').play()

const controller = new AbortController()
suno.loadAll({ signal: controller.signal })
 
// Cancel if the user navigates away
controller.abort()

suno.setPlaybackRate(0.5) // Global slowmo
voice.setPlaybackRate(1.5) // This voice plays at 0.75× effective