Media@knitui/media

Audio

A hybrid, cross-platform audio player. On web it drives the real browser HTMLAudioElement (+ Web Audio / MediaSession); on React Native it drives expo-audio.

WebiOSAndroid7 style slots28 own props12 examples

Stories Source Tests Open in Storybook

import { Audio } from "@knitui/media";

Playground

Loading playground…

size

controls

true

Playground

<Audio
  source="https://samplelib.com/mp3/sample-30s.mp3"
  size="md"
  controls
  loop={false}
  muted={false}
/>

Examples

Basic

Loading example…

BasicSource Storybook

With Metadata

Loading example…

With MetadataSource Storybook

Lock Screen

Lock-screen / now-playing controls with a cover preview. Setting lockScreen publishes the title/artist/album/artwork to the OS: on native (expo-audio) it owns the iOS lock screen / Android media notification, and on web it drives the browser MediaSession API — so the artwork shows as the cover in the OS media controls / hardware-key UI. Play it, then check your system media controls (or lock the device on a native build).

Loading example…

Lock ScreenSource Storybook

Looping

Loading example…

LoopingSource Storybook

Sizes

Loading example…

SizesSource Storybook

Custom Control Bar

Compose a custom bar from the exported parts.

Loading example…

Custom Control BarSource Storybook

Headless

Headless: no transport, just the header. Drive it via Audio.useAudio().

Loading example…

HeadlessSource Storybook

Styles

Per-slot style overrides.

Loading example…

StylesSource Storybook

Themed

Theme-driven recolor. The whole player is built on $colorN ramp tokens, so dropping it under a <Theme> recolors it with zero per-component logic — the same property that themes Button/ActionIcon. No hardcoded colors anywhere.

Loading example…

ThemedSource Storybook

Alternate Source

Loading example…

Alternate SourceSource Storybook

Long Track

A full, minutes-long track — gives the scrubber real range to drag across and a meaningful elapsed/remaining readout (the short sample clips are only seconds).

Loading example…

Long TrackSource Storybook

Two Players

Two players sharing ONE shared audio engine (the default singleton). Press play on one, then play on the other: the engine switches to the second track and the first pauses — there is only ever ONE <audio> element. Return to the first and it resumes from where you left off.

Loading example…

Two PlayersSource Storybook

Props

Prop	Type	Default	Description
`source` required	`string \| number \| AudioSourceObject \| null`	`https://samplelib.com/mp3/sample-30s.mp3`	The audio to play.
`album`	`string \| undefined`	—	Now-playing album.
`artist`	`string \| undefined`	—	Now-playing artist.
`artwork`	`string \| undefined`	—	Artwork image URL.
`autoPlay`	`boolean \| undefined`	—	Begin playback as soon as the source is ready.
`controls`	`ReactNode`	`true`	The control chrome. `true` (default) renders the built-in control bar; `false` renders no chrome; a node renders custom chrome inside the context (compose `Audio.*` parts).
`getController`	`((controller: AudioController) => void) \| undefined`	—	Receives the controller once ready.
`id`	`string \| undefined`	—	Stable identity for the shared-engine registry. Defaults to a generated id (each `<Audio>` is its own player); pass an explicit `id` to make two mounts address the SAME shared-engine slot.
`keyboard`	`boolean \| undefined`	—	Enable keyboard shortcuts (space, arrows, m, …). Default `true`.
`label`	`string \| undefined`	—	Accessible label for the player region. Default `"Audio player"`.
`lockScreen`	`boolean \| AudioMetadata \| undefined`	—	Enable lock-screen / now-playing controls with the given metadata. `true` derives metadata from `title`/`artist`/`album`/`artwork`.
`loop`	`boolean \| undefined`	`false`	Replay automatically on end.
`maxWidth`	`number \| Animated.AnimatedNode \| GetThemeValueForKey<"maxWidth"> \| null \| undefined`	—	Frame max width.
`muted`	`boolean \| undefined`	`false`	Start muted (required by browsers for unattended autoplay).
`onEnded`	`(() => void) \| undefined`	—
`onError`	`((error: AudioError) => void) \| undefined`	—
`onPlayingChange`	`((playing: boolean) => void) \| undefined`	—
`onReady`	`(() => void) \| undefined`	—	Fired once the player first becomes ready to play.
`onStatusChange`	`((status: AudioStatus, error: AudioError \| null) => void) \| undefined`	—
`onTimeUpdate`	`((currentTime: number) => void) \| undefined`	—
`playbackRate`	`number \| undefined`	—	Initial playback rate.
`shouldCorrectPitch`	`boolean \| undefined`	—	Correct pitch when the rate changes. Default `true`.
`showHeader`	`boolean \| undefined`	—	Show the metadata header. Defaults to `true` when any metadata is given.
`size` system	`"xxs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxl" \| undefined` xxs · xs · sm · md · lg · xl · xxl	`md`	Control sizing scale. Default `'md'`.
`styles` system	`SlotStyles<AudioStyles> \| undefined`	—	Per-slot style overrides.
`testID`	`string \| undefined`	—
`title`	`string \| undefined`	—	Now-playing title (shown in the header + used for lock-screen metadata).
`updateInterval`	`number \| undefined`	—	Status / `timeUpdate` interval, ms (native). The unified name.
`volume`	`number \| undefined`	—	Initial volume, 0..1.
`width`	`number \| GetThemeValueForKey<"width"> \| Animated.AnimatedNode \| null \| undefined`	—	Frame width.

Style slots

Every part of Audio can be styled through the styles prop. Explicit props on the component always win over slot styles.

Slot	Usage
`artist`	`styles={{ artist: { … } }}`
`artwork`	`styles={{ artwork: { … } }}`
`controlBar`	`styles={{ controlBar: { … } }}`
`header`	`styles={{ header: { … } }}`
`root`	`styles={{ root: { … } }}`
`time`	`styles={{ time: { … } }}`
`title`	`styles={{ title: { … } }}`