Skip to content
Kimenpre-v1documentation home
Color scheme

ki-audio

Use ki-audio for voice notes, generated speech and other recordings a listener chooses to play. Give each recording a concise title and link to its transcript with transcript-href.

Theme for this example
Color scheme for this example

[Three rising tones, separated by short pauses.]

<ki-audio src="/docs/_astro/three-tones.Z1QtA_8x.wav" title="Three rising tones" transcript-href="#three-tones-transcript"></ki-audio>
<p id="three-tones-transcript">[Three rising tones, separated by short pauses.]</p>

Playback and keyboard controls

Playback starts when the listener activates Play. Once the duration is available, focus Seek and press Left or Right to move five seconds along the timeline. In a right-to-left layout, Left moves towards the end of the recording. Press Space on Seek to toggle playback. Focus Playback speed and choose a rate using the platform’s standard select controls.

The title names the player group. The seek control announces the elapsed and total times, for example “1:24 of 12:05”. Set time-label with the {elapsed} and {duration} placeholders to translate that announcement.

Sources and playback events

src and transcript-href accept relative references and HTTP(S) URLs. The guarded catalog also applies the host’s origin allowlist when configured. Use the player’s play, pause, timeupdate and ended events to observe the session. A catalog action can be bound to ended.

Choose speeds with a comma-separated list such as rates="0.75,1,1.5". Normal speed is always available. The default menu offers 0.75×, 1×, 1.25×, 1.5× and 2×.

API reference

When to use: play a voice note, interview, or other prerecorded audio that a person deliberately starts. Provide a title and the equivalent text transcript URL when available.

When not to use: show video (use ki-video), play an ambient loop or start playback automatically, or record audio.

Properties & attributes

AttributePropertyTypeDefaultDescription
titleaudioTitlestring | undefined'Audio player'Visible title and accessible name of the player.
error-labelerrorLabelstring'Audio could not be played'Message shown if playback cannot start or the recording fails to load.
mute-labelmuteLabelstring'Mute'Accessible name of the mute button.
pause-labelpauseLabelstring'Pause'Accessible name of the pause button.
play-labelplayLabelstring'Play'Accessible name of the play button.
ratesratesstring'0.75,1,1.25,1.5,2'Comma-separated playback speeds between 0.25 and 4. Normal speed (1) is always available.
seek-labelseekLabelstring'Seek'Accessible name of the timeline slider.
speed-labelspeedLabelstring'Playback speed'Accessible label for the playback-rate picker.
srcsrcstring–Source URL for the recording. Use an HTTP(S) URL or a relative URL.
time-labeltimeLabelstring | undefined'{elapsed} of {duration}'Accessible time template. Keep the {elapsed} and {duration} placeholders.
transcript-hreftranscriptHrefstring | undefined–URL for the recording's text transcript. Use an HTTP(S) URL or a relative URL.
transcript-labeltranscriptLabelstring'Read the transcript'Text of the transcript link.
unmute-labelunmuteLabelstring'Unmute'Accessible name of the unmute button.

Events

EventDetail typeDescription
endedCustomEvent<void>Forwarded when the recording ends. The catalog can bind a declared action here.
pauseCustomEvent<void>Forwarded when native playback pauses.
playCustomEvent<void>Forwarded when the native playback state switches to playing.
timeupdateCustomEvent<void>Forwarded when the native playback position is updated.

CSS parts

PartDescription
muteMute and unmute control.
playPlay and pause control.
playerThe named group and themed surface.
progressPlayed portion of the timeline rail.
seekNative seek slider.
speedNative playback-rate picker.
statusPlayback failure message.
timeElapsed and total time readouts.
titleVisible recording title.
trackTimeline rail.
transcriptTranscript link.

CSS custom properties

The public styling contract of ki-audio: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-audio-backdrop-filterComplete backdrop filter applied to the player, off by default.
--ki-audio-bgBackground behind the player and transcript link.
--ki-audio-bg-imageOptional image painted over the player background.
--ki-audio-borderBoundary of the player panel.
--ki-audio-fgText on the player background.
--ki-audio-progress-bgColour of the elapsed timeline and seek thumb.
--ki-audio-radiusCorner radius of the player panel.
--ki-audio-speed-radiusCorner radius of the playback speed button.
--ki-audio-title-familyFont family of the recording title.
--ki-audio-track-bgColour of the inactive timeline.
--ki-button-ghost-neutral-disabled-bgcolor used by the button component for ghost neutral disabled background.
--ki-button-ghost-neutral-disabled-bordercolor used by the button component for ghost neutral disabled border.
--ki-button-ghost-neutral-disabled-fgcolor used by the button component for ghost neutral disabled foreground.
--ki-button-ghost-neutral-hover-bgcolor used by the button component for ghost neutral hover background.
--ki-button-ghost-neutral-hover-bordercolor used by the button component for ghost neutral hover border.
--ki-button-ghost-neutral-hover-fgcolor used by the button component for ghost neutral hover foreground.
--ki-button-ghost-neutral-rest-bgcolor used by the button component for ghost neutral rest background.
--ki-button-ghost-neutral-rest-bordercolor used by the button component for ghost neutral rest border.
--ki-button-ghost-neutral-rest-fgcolor used by the button component for ghost neutral rest foreground.
--ki-button-primary-neutral-disabled-bgcolor used by the button component for primary neutral disabled background. Deliberate deviation: Figma disabled is Surface/disabled_base_em gray.100 with gray.400 text (≈1.4:1); Kimen keeps gray.200 for contrast (precedent 010 D2, pending founder ratification).
--ki-button-primary-neutral-disabled-bordercolor used by the button component for primary neutral disabled border.
--ki-button-primary-neutral-disabled-fgcolor used by the button component for primary neutral disabled foreground. Deliberate deviation: Figma disabled text is text/base_em gray.400 (≈1.4:1 on gray.100); Kimen keeps text.muted gray.700 for readable disabled text (precedent 010 D2, pending founder ratification).
--ki-button-primary-neutral-hover-bgcolor used by the button component for primary neutral hover background (MarsUI: rest fill; hover lightening comes from the hover overlay).
--ki-button-primary-neutral-hover-bordercolor used by the button component for primary neutral hover border (MarsUI bevel top/inline edge).
--ki-button-primary-neutral-hover-fgcolor used by the button component for primary neutral hover foreground.
--ki-button-primary-neutral-rest-bgcolor used by the button component for primary neutral rest background (MarsUI Surface/primary_med_em, brand 500).
--ki-button-primary-neutral-rest-bordercolor used by the button component for primary neutral rest border (MarsUI bevel top/inline edge).
--ki-button-primary-neutral-rest-fgcolor used by the button component for primary neutral rest foreground.
--ki-control-border-widthStroke width of the boundary of a compact control.
--ki-control-radius-trackCorner radius of a track containing adjacent controls.
--ki-control-size-mdMedium control track height, 40 CSS px at the default root size.
--ki-control-size-smSmall control track height, 32 CSS px at the default root size.
--ki-corner-activity-markRound corners for rings and typing dots.
--ki-corner-inlineSmall radius for an outline around inline content.
--ki-density-target-minThe smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1).
--ki-focus-ring-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-offsetGap between a focusable component and its keyboard focus ring.
--ki-focus-ring-widthThickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once.
--ki-glyph-size-mdMedium glyph for body content (20px at the default root size).
--ki-glyph-size-smSmall glyph for dense layouts (16px at the default root size).
--ki-media-layout-inline-maxMaximum inline size of a self-contained media control panel.
--ki-scale-control-coarse-targetMinimum grip target when a value scale has a coarse primary pointer.
--ki-scale-control-track-heightThickness of the inactive rail of a value scale.
--ki-spacing-action-insetInterior space at the edge of an action surface or divider.
--ki-spacing-blockDeprecated alias kept for pre-Fase-1 consumers; use ki.space.xl.
--ki-spacing-media-captionBlock spacing between a media frame and its caption.
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-line-height-body-1semantic dimension for typography line height body 1.
--ki-typography-line-height-caption-2semantic dimension for typography line height caption 2.
--ki-typography-size-body-1semantic dimension for typography size body 1.
--ki-typography-size-caption-2semantic dimension for typography size caption 2.
--ki-typography-underline-offsetGap between text and its underline.
--ki-typography-underline-thicknessStroke width of a resting text underline.
--ki-typography-weight-body-mediumsemantic font weight for typography weight body medium.

Workshop

Open ki-audio in Storybook