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
  mutePersistKey?: string // Seeds + persists muted state via localStorage[key]
}

const suno = new Suno({ manifest: MANIFEST, muted: true })
suno.isMuted() // true
suno.isRunning // false
 
await suno.load('hero-ambient') // safe from anywhere
 
// Inside a click handler (ctx auto-resumes on this gesture):
suno.get('hero-ambient').play({ loop: true }) // Voice — runs silently (master gain is 0)
suno.isRunning // false — still muted
 
await suno.unlock({ unmute: true }) // ensures ctx resume + unmutes
suno.isRunning // true — ambient becomes audible mid-loop

await suno.unlock()   // ctx.resume() if needed
suno.setMuted(false)  // or mixer.setMuted(false, { fade: 0.3 }) for a fade-in

suno.on('mutedchange', ({ muted }) => { /* user unmuted / muted */ })
suno.player.on('statechange', (state) => { /* raw ctx state */ })

// 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 })

suno.setMuted(true) // snapshots current volume, ramps master to 0
suno.setMuted(false) // restores snapshot
suno.toggleMuted()
suno.isMuted()
 
suno.on('mutedchange', ({ muted }) => {
  document.documentElement.dataset.muted = muted ? 'true' : 'false'
})

const suno = new Suno({ manifest: MANIFEST, mutePersistKey: 'my-app-muted' })

<script
  dangerouslySetInnerHTML={{
    __html: Suno.preHydrationMutedScript('my-app-muted'),
  }}
/>

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)
  offset?: number // Buffer position (seconds) at which to start (default: 0)
}

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 }
  seek: { voice: Voice; from: number; to: number } // Fired by seek() — includes pre/post position
  regionchange: { voice: Voice; region: { start: number; end: number } | null } // Fired by setRegion()
}

import { Mixer } from '@joycostudio/suno'
 
const mixer = new Mixer({
  suno,
  fadeOutDuration: 0.5, // seconds (default)
  fadeInDuration: 0, // seconds (default: instant)
  muteFadeDuration: 0.2, // seconds (default) — used by setMuted/toggleMuted
  autoPauseOnHidden: true, // fade master volume to 0 when tab hidden, fade back on return (default: true)
})

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' }
}

// Route A
mixer.setAmbient('forest', { fadeIn: 2, fadeOut: 1 })
 
// Route B — forest fades out, ocean fades in
mixer.setAmbient('ocean')
 
// Route with no ambient — fade out what's playing
mixer.setAmbient(null)

mixer.setMuted(true) // fade out over muteFadeDuration
mixer.setMuted(false, { fade: 1 }) // 1s unmute fade
mixer.toggleMuted()

import { WebAudioPlayer } from '@joycostudio/suno'
 
const player = new WebAudioPlayer()
 
player.audioContext // Lazily creates AudioContext
player.masterOutput // Master GainNode
player.state        // 'running' | 'suspended' | 'closed' — raw AudioContext state
player.isRunning    // true if state === 'running' (raw ctx-level flag)
 
await player.unlock() // ctx.resume() — must be called from a user gesture
player.setMasterVolume(0.8)
player.getMasterVolume()
 
await player.pause()
await player.resume()
await player.dispose()
 
// Subscribe to raw ctx transitions
player.on('statechange', (state) => {})

import { rampTo, ANTI_POP_RAMP } from '@joycostudio/suno'

// 10 ms anti-pop transition on a filter cutoff
rampTo(filter.frequency, ctx, 800, ANTI_POP_RAMP)
 
// Musical 2s duck on a custom bus
rampTo(sfxBus.gain, ctx, 0.3, 2)
 
// Stop a source 5 ms after a fade-out lands
const endsAt = rampTo(source.gain, ctx, 0, 0.5)
node.stop(endsAt + 0.005)

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

// Self-managed: provider creates and disposes on unmount
<SunoProvider manifest={MANIFEST}>
  {children}
</SunoProvider>
 
// Self-managed with extra Suno options (everything except `manifest`):
<SunoProvider manifest={MANIFEST} options={{ mutePersistKey: 'my-app-muted' }}>
  {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>

const { unlocked } = useAutoUnlock(undefined, {
  onUnlock: () => console.log('unlocked'),
})

const isMobile = useIsMobile()
useAutoUnlock(undefined, { enabled: !isMobile })

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' — raw AudioContext state
  masterVolume: number
  playbackRate: number
  muted: boolean // suno-owned mute flag (persists via `mutePersistKey`)
  isRunning: boolean // !muted && ctx running — audio actually emitted
}
 
const state = useSunoState()

// Instant — reads Suno from context (or pass one explicitly)
const { muted, setMuted, toggleMuted } = useMuted()
 
// With a Mixer — mute/unmute is faded (uses mixer.muteFadeDuration)
const { muted, toggleMuted } = useMuted(mixer)

const voice = source.play({ loop: true })
 
// Seek to 30 seconds (pop-free even while playing)
voice.seek(30)
 
// Loop only between 10 s and 25 s
voice.setRegion({ start: 10, end: 25 })
 
// Play a one-shot clip that stops at 25 s instead of at the buffer end
const oneShot = source.play({ loop: false })
oneShot.setRegion({ start: 10, end: 25 })
 
// Clear the region — resume whole-buffer playback
voice.setRegion(null)
 
// Start a new voice at an arbitrary offset
source.play({ offset: 15 })
 
// React to position changes
voice.on('seek', ({ from, to }) => console.log(`seeked ${from.toFixed(2)} → ${to.toFixed(2)}`))
voice.on('regionchange', ({ region }) => console.log('region', region))

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

import { Mixer } from '@joycostudio/suno'
import { useSuno } from '@joycostudio/suno/react'
 
function AudioUI() {
  const suno = useSuno()
  const mixerRef = useRef<Mixer | null>(null)
  if (!mixerRef.current) mixerRef.current = new Mixer({ suno })
  const mixer = mixerRef.current
 
  useEffect(() => {
    return () => {
      mixer.stopAll({ fadeOut: 0 })
      mixer.dispose()
    }
  }, [mixer])
 
  return (
    <>
      <button onClick={() => mixer.play('click')}>Play</button>
      <button onClick={() => mixer.stopAll()}>Fade out all</button>
    </>
  )
}

import { Mixer } from '@joycostudio/suno'
import { useSuno } from '@joycostudio/suno/react'
 
function AmbientForRoute({ route }: { route: string }) {
  const suno = useSuno()
  const mixerRef = useRef<Mixer | null>(null)
  if (!mixerRef.current) mixerRef.current = new Mixer({ suno })
 
  useEffect(() => {
    const key = route === '/menu' ? 'menu-ambient' : route === '/game' ? 'game-ambient' : null
    mixerRef.current!.setAmbient(key, { fadeIn: 2, fadeOut: 1 })
  }, [route])
 
  return null
}

import { SunoProvider, useAutoUnlock, useMuted } from '@joycostudio/suno/react'
 
function App() {
  return (
    <SunoProvider manifest={MANIFEST} options={{ mutePersistKey: 'my-app-muted' }}>
      <Unlock />
      <MuteToggle />
    </SunoProvider>
  )
}
 
function Unlock() {
  useAutoUnlock()
  return null
}
 
function MuteToggle() {
  const { muted, toggleMuted } = useMuted()
  return <button onClick={toggleMuted}>{muted ? 'Unmute' : 'Mute'}</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()

Voice volume  ×  Source bus volume  ×  Master volume  =  Final output

effectiveRate = voice.localRate × suno.globalRate

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