Getting Started

Install and run Ozen-web

Overview

Ozen-web is a static web application that runs entirely in your browser. You can:

  1. Use the hosted version (easiest) — No setup required
  2. Run locally for development — Full control and offline access
  3. Deploy your own instance — Host on GitHub Pages, Netlify, or any static host

Option 1: Use Hosted Version

The fastest way to get started is using the hosted version:

🌐 https://ucpresearch.github.io/ozen-web/live/

Simply visit the URL and drag an audio file (WAV, FLAC, MP3, OGG) to begin analyzing.

Tip

Bookmark the URL for quick access. All processing happens locally in your browser — no data is uploaded to servers.

Loading Your First Audio File

  1. Drag and drop a WAV, FLAC, MP3, or OGG file onto the interface

    OR

    Click “Load Audio” button and select a file

  2. Wait for the waveform to appear

  3. The spectrogram will load automatically (or zoom in for long files)

  4. Enable acoustic overlays using checkboxes: Pitch, Formants, Intensity

Don’t have an audio file handy? Record directly in the browser by clicking the microphone icon 🎤 (requires microphone permission).

What’s Next?

Option 2: Run Locally

For development or offline use, run Ozen-web on your machine.

Prerequisites

  • Any local web server, for instance python -m http.server 8080, started from one of the parent directories

Download

  • git clone https://github.com/ucpresearch/ozen-web.git

  • cd ozen-web/docs

  • python -m http.server 8080 (adapt the port – 8080 – as necessary)

  • Open the following url (adapt the port as necessary): (http://localhost:8080/live/index.html)[http://localhost:8080/live/index.html]
    notice that this method doesn’t use https, and your browser may complain about it

Option 3: Deploy Your Own Instance

The build/ or docs/live (same content) folder will work with any static file host:

  • AWS S3 + CloudFront
  • Google Cloud Storage
  • Azure Static Web Apps
  • Cloudflare Pages
  • GitLab Pages

Just upload the build/ folder’s contents.

Configuration

Backend Selection

Ozen-web supports multiple WASM backends:

Backend Source License Offline
praatfan-local static/wasm/ MIT/Apache-2.0 ✅ Yes
praatfan GitHub Pages CDN MIT/Apache-2.0 ❌ No
praatfan-gpl GitHub Pages CDN GPL ❌ No

Select the backend using the dropdown in the app interface.

See WASM Backends Reference for detailed comparison.

Custom Configuration

Create static/config.yaml to customize default settings:

# Example configuration
backend: "praatfan-local"
maxFrequency: 5000
showPitch: true
showFormants: true
theme: "dark"

See Configuration Reference for all options.

Troubleshooting

WASM Fails to Load

  • Check backend selection: Try switching between backends in the dropdown
  • Clear browser cache: Hard refresh with Ctrl+Shift+R (Cmd+Shift+R on Mac)
  • Check browser console: Open DevTools (F12) → Console tab for error messages

Audio File Won’t Load

  • Supported formats: WAV, FLAC, MP3, OGG (16-bit or 24-bit PCM for WAV)
  • File size: Files >100MB may be slow; try shorter clips

Long Audio Files Show “Zoom in for spectrogram”

This is expected behavior for files >60 seconds. Zoom in to a window ≤60s to trigger analysis.

See Features: Long Audio Handling for details.

Getting Help

What’s Next?

Ready to dive deeper? Try the:

All set? Head to the Tutorial to learn the complete workflow. →

Back to top