oziAudio

Version: 3.0.0 — Updated: 2026-05-27

Description

Declarative audio component for web interfaces. Supports three operation modes — player, recorder and full — all activated via an HTML attribute on a container element. Integrates audio file playback, microphone recording, preview of recorded content and automatic submission to the backend via oziLoadData.

The visual is completely independent of CSS frameworks — all appearance is controlled by CSS tokens --ozi-audio-* in :root, allowing full customization without touching the plugin code. Icons are external SVG files loaded on demand with automatic caching.

Examples

[1] Player mode

Audio playback with progress bar, volume and speed control.

<div
    data-ozi-audio="player"
    data-ozi-audio-url="/storage/audio/podcast.mp3"
    data-ozi-audio-title="Episode 01">
</div>

Player without volume and speed controls:

<div
    data-ozi-audio="player"
    data-ozi-audio-url="/storage/audio/intro.mp3"
    data-ozi-audio-volume="false"
    data-ozi-audio-speed="false">
</div>

[2] Recorder mode

Microphone recording with real-time timer, preview and backend submission.

<div
    data-ozi-audio="recorder"
    data-ozi-audio-save-url="/api/audio/save"
    data-ozi-audio-save-field="recording">
</div>

Recorder without preview:

<div
    data-ozi-audio="recorder"
    data-ozi-audio-preview="false"
    data-ozi-audio-save-url="/api/audio/save">
</div>

[3] Full mode — player + recorder

Player and recorder combined in the same component. Allows playing a base audio and recording a new version.

<div
    data-ozi-audio="full"
    data-ozi-audio-url="/storage/audio/base.mp3"
    data-ozi-audio-title="Recording"
    data-ozi-audio-save-url="/api/audio/save"
    data-ozi-audio-save-field="audio_file">
</div>

[4] Customization via CSS tokens

/* Dark theme */
.my-player {
    --ozi-audio-bg: rgba(30, 30, 30, 0.95);
    --ozi-audio-border: rgba(255, 255, 255, 0.08);
    --ozi-audio-color: #555;
    --ozi-audio-color-secondary: #7c3aed;
    --ozi-audio-text: #ccc;
}

Features

• Three modes — player, recorder and full
• Full player — progress bar, volume, mute and speed control
• Recorder — microphone via MediaRecorder with real-time timer
• Preview — native player after recording for review before saving
• Automatic submission — backend via oziLoadData
• Auto-pause — pauses concurrent instances when playback starts
• MutationObserver — detects and initializes elements inserted into the DOM
• External SVG icons — loaded on demand with cache, replaceable per project
• CSS tokens — 100% customizable appearance via --ozi-audio-*

HTML Attributes

[1] Operation Mode

[2] Player Configuration

[3] Recorder Configuration

[4] Playback Speeds

1x → 1.25x → 1.5x → 1.75x → 2x → 0.75x → 1x

CSS Tokens

:root {
    /* Colors */
    --ozi-audio-color: #b8b8b9;
    --ozi-audio-color-secondary: #ff7f50;
    --ozi-audio-text: #808080;
    --ozi-audio-text-secondary: #dfdfdf;

    /* Container */
    --ozi-audio-bg: rgba(255, 255, 255, 0.77);
    --ozi-audio-shadow: rgba(117, 108, 108, 0.22);
    --ozi-audio-border: rgba(255, 255, 255, 0.22);
    --ozi-audio-radius: 15px;
    --ozi-audio-padding: 8px 10px;
    --ozi-audio-width-min: 250px;
    --ozi-audio-width-max: 350px;

    /* Bars */
    --ozi-audio-timeline-height: 15px;
    --ozi-audio-volume-height: 7px;

    /* Record button */
    --ozi-audio-record-bg: #dc3545;
    --ozi-audio-record-bg-hover: #bb2d3b;
    --ozi-audio-record-text: #ffffff;

    /* Save button */
    --ozi-audio-save-bg: #198754;
    --ozi-audio-save-bg-hover: #157347;
    --ozi-audio-save-text: #ffffff;

    /* Icons */
    --ozi-audio-icon-play-size: 20px;
    --ozi-audio-icon-volume-size: 18px;
    --ozi-audio-icon-record-size: 16px;
    --ozi-audio-icon-save-size: 14px;
}

Events

$('#myAudio').on('ozi:audio-recorded', function(e, payload) {
    console.log(payload.duration);  // duration in seconds
    console.log(payload.mimeType);  // e.g.: audio/webm
    console.log(payload.size);      // size in bytes
    console.log(payload.file);      // File object
});

Public API