🎮 Player Functions

Expo Sonic provides a modern API to control audio playback. Below, functions are grouped by category: Playback, Session, and Metadata.

📦 Import

import { ExpoSonicPlayer } from "expo-sonic-ios-player";

▶️ Playback Methods

Method	Signature	Description
`play`	`(options: AudioPlaybackOptions) => Promise<void>`	Start playing audio with options.
`pause`	`() => Promise<void>`	Pause the current playback.
`resume`	`() => Promise<void>`	Resume paused audio.
`stop`	`() => Promise<void>`	Stop and release the audio player.
`seek`	`(seconds: number) => Promise<void>`	Seek to a specific time in seconds.

`AudioPlaybackOptions`

interface AudioPlaybackOptions {
  url: string;
  title: string;
  artist: string;
  artwork?: string;
  duration?: number;
  album?: string;
  description?: string;
  isLive?: boolean;
  useSpatialAudio?: boolean; // ⚠️ Experimental
}

Property	Type	Required	Description
`url`	`string`	✅	Audio URL to play.
`title`	`string`	✅	Track title.
`artist`	`string`	✅	Artist name.
`artwork`	`string`	❌	Artwork image URL.
`duration`	`number`	❌	Duration in seconds.
`album`	`string`	❌	Album name.
`description`	`string`	❌	Track description.
`isLive`	`boolean`	❌	Whether the track is a live stream.
`useSpatialAudio`	`boolean`	❌	⚠️ Experimental. May not work as expected.

🧠 Session Control

Method	Signature	Description
`toggleAmbientMode`	`<T extends boolean>(enabled: T) => Promise<void>`	Enables or disables ambient audio mode (background).

🖼️ Metadata Management

Method	Signature	Description
`setMetaDataForCurrentTrack`	`(metadata: TrackMetadata) => Promise<void>`	Update metadata shown on lock screen and control center.

`TrackMetadata`

interface TrackMetadata {
  title?: string;
  artist?: string;
  album?: string;
  artwork?: string;
  duration?: number;
}

Property	Type	Description
`title`	`string`	Track title.
`artist`	`string`	Artist name.
`album`	`string`	Album name.
`artwork`	`string`	Artwork URL.
`duration`	`number`	Duration in seconds.

💡 Example

await ExpoSonicPlayer.play({
  url: "https://example.com/track.mp3",
  title: "Bloom",
  artist: "ODESZA",
  artwork: "https://example.com/cover.jpg",
  duration: 180,
  isLive: false,
});

await ExpoSonicPlayer.pause();
await ExpoSonicPlayer.resume();
await ExpoSonicPlayer.seek(90);
await ExpoSonicPlayer.stop();

await ExpoSonicPlayer.setMetaDataForCurrentTrack({
  title: "Bloom",
  artist: "ODESZA",
  artwork: "https://example.com/cover.jpg",
  duration: 180,
});

await ExpoSonicPlayer.toggleAmbientMode(true);

On this page