Voxis Python Guide

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")

Learn the Voxis Python API from the beginning.