Voxis Python Guide
Description: Learn the offline Voxis Python workflow from zero: imports, AudioClip, Pipeline, effects, presets, clip editing, and export.

Offline Python Guide

# Learn the Voxis Python API from the beginning.

This guide explains what to import, what `AudioClip` and `Pipeline` do, when to use direct effect imports or the `effects` namespace, and how to export the final result.

    from voxis import AudioClip, Pipeline
    from voxis import effects

    clip = AudioClip.from_file("input.wav")
    pipeline = (
        Pipeline(sample_rate=clip.sample_rate, channels=clip.channels, block_size=2048)
        >> [effects.compressor(threshold_db=-18.0, ratio=3.0)]
    )

## 1. Install Voxis

    python -m pip install voxis

## 2. Your first imports

The two most important building blocks are:

- `AudioClip`: loads audio, stores metadata, and gives you clip editing, rendering, and export methods.
- `Pipeline`: describes an ordered list of effects to run on the clip.

    from voxis import AudioClip, Pipeline

## 3. Load an audio file

    from voxis import AudioClip

    clip = AudioClip.from_file("voice.wav")

    print(clip.sample_rate)
    print(clip.channels)
    print(clip.duration_seconds)

`AudioClip.from_file(...)` decodes the audio and returns an `AudioClip` object you can inspect, process, and export. The main duration property is `clip.duration_seconds`. Voxis also exposes `clip.duration_ms` as a convenience alias when you want milliseconds.

## 4. Start by inspecting the clip

If you are learning the library, it is normal to begin with `print(...)` so you can see what Voxis loaded and what the package exposes.

    from voxis import AudioClip, effect_names, preset_names

    clip = AudioClip.from_file("voice.wav")

    print(type(clip).__name__)
    print(clip.sample_rate)
    print(clip.channels)
    print(clip.duration_seconds)
    print(clip.duration_ms)
    print(len(effect_names()))
    print(preset_names())

This is a good first step before you build bigger pipelines.

## 5. Understand path resolution

Relative paths are resolved from the Python file that called the API, not from the terminal location.

    project/
      scripts/
        clean_voice.py
        voice.wav

    from voxis import AudioClip

    clip = AudioClip.from_file("voice.wav")

If the file lives in another folder, use normal relative navigation:

    AudioClip.from_file("../voice.wav")
    AudioClip.from_file("../assets/voice.wav")
    AudioClip.from_file("assets/voice.wav")

## 6. Two ways to import effects

You can work with Voxis effects in two styles.

### Option A: direct imports

    from voxis import AudioClip, Pipeline, compressor, delay, distortion, lowpass

    clip = AudioClip.from_file("input.wav")
    pipeline = (
        Pipeline(sample_rate=clip.sample_rate, channels=clip.channels, block_size=2048)
        >> [
            distortion(drive=2.5),
            lowpass(frequency_hz=8000.0, stages=2),
            delay(delay_ms=135.0, feedback=0.32, mix=0.22),
            compressor(threshold_db=-18.0, ratio=3.5),
        ]
    )

Use this style when you already know which effects you want.

### Option B: the `effects` namespace

    from voxis import AudioClip, Pipeline
    from voxis import effects

    clip = AudioClip.from_file("input.wav")
    pipeline = (
        Pipeline(sample_rate=clip.sample_rate, channels=clip.channels, block_size=2048)
        >> [
            effects.distortion(drive=2.5),
            effects.lowpass(frequency_hz=8000.0, stages=2),
            effects.delay(delay_ms=135.0, feedback=0.32, mix=0.22),
            effects.compressor(threshold_db=-18.0, ratio=3.5),
        ]
    )

Use the namespace style when you want better discoverability or a cleaner import block.

## 7. What an effect call does

Calling `effects.compressor(...)` or `distortion(...)` does not process the file immediately. It creates a step that you place inside a `Pipeline`.

    from voxis import effects

    compressor_step = effects.compressor(
        threshold_db=-18.0,
        ratio=3.0,
        makeup_db=1.5,
    )

    print(compressor_step)

Think of the pipeline as the recipe and `clip.apply_pipeline(...)` as the render step.

## 8. Build a pipeline

A `Pipeline` is configured with sample rate, channel count, and an optional block size. Then you append effects with `>>`.

    pipeline = (
        Pipeline(sample_rate=clip.sample_rate, channels=clip.channels, block_size=2048)
        >> [
            effects.noise_reduction(strength=0.55, fft_size=1024),
            effects.de_reverb(amount=0.35, tail_ms=180, fft_size=2048, hop_size=256),
            effects.compressor(threshold_db=-18.0, ratio=3.0, makeup_db=1.5),
        ]
    )

## 9. Render the processed clip

    processed = clip.apply_pipeline(pipeline)

This runs the pipeline and returns a new `AudioClip`.

## 10. Export the result

    processed.export("output.wav")
    processed.export("master.mp3", bitrate="192k", format="mp3", sample_rate=44_100)

Like input paths, relative export paths are resolved from the calling Python file.

## 11. Use presets

Voxis also ships presets when you want a fast starting point.

    processed = clip.apply("vocal_enhance")
    processed.export("voice_master.wav")

You can inspect what is available:

    from voxis import preset_names

    print(preset_names())

## 12. Edit the clip directly

Not every change has to go through a pipeline. `AudioClip` also exposes direct editing methods.

    edited = (
        clip.fade_in(180.0)
        .trim(start_ms=50.0, end_ms=12000.0)
        .remove_silence(threshold_db=-50.0, min_silence_ms=90.0, padding_ms=15.0)
        .remove_dc_offset()
        .normalize(headroom_db=1.0)
    )

    edited.export("voice_edited.wav")

Each direct editing method returns a new `AudioClip`. That means `edited` is already the processed clip, so you can keep chaining methods on it or export it immediately.

## 13. Inspect the catalog

    from voxis import effect_names, preset_names

    print(len(effect_names()))
    print(effect_names())
    print(preset_names())

This is useful when you are exploring the library or building your own UI on top of Voxis.

## 14. A complete starter script

    from voxis import AudioClip, Pipeline
    from voxis import effects

    clip = AudioClip.from_file("voice.wav")

    pipeline = (
        Pipeline(sample_rate=clip.sample_rate, channels=clip.channels, block_size=2048)
        >> [
            effects.noise_reduction(strength=0.55, fft_size=1024),
            effects.de_reverb(amount=0.35, tail_ms=180, fft_size=2048, hop_size=256),
            effects.compressor(threshold_db=-18.0, ratio=3.0, makeup_db=1.5),
            effects.high_shelf(frequency_hz=9000.0, gain_db=1.5),
        ]
    )

    processed = clip.apply_pipeline(pipeline)
    processed.export("voice_clean.wav")