AmbientMachine

A simple ambient sound looper that layers audio files continuously.

What It Does

AmbientMachine plays multiple audio loops simultaneously, creating a living ambient soundscape from simple audio files and a YAML configuration. Loops can fade in and out, vary in length randomly, play probabilistically, and start at staggered intervals. Drone loops play continuously without cycle boundaries. The result is evolving, generative soundscapes.

Requirements

• Python 3.10 or higher

Quick Start

Install the package:

pip install -e .

Create a configuration file (e.g., config.yml):

master_volume: 0.8
sample_rate: 44100

defaults:
  fade_in: 2.0

loops:
  - file: audio/rain.wav
    volume: 0.7
    loop_length: 10.0

  - file: audio/drone.mp3
    volume: 0.5
    fade_in: 3.0

  - file: audio/birds.flac
    volume: 0.6
    loop_length: 8.0

Run AmbientMachine:

ambientmachine config.yml

Usage

Basic playback:

ambientmachine config.yml

With seed for reproducible sessions:

ambientmachine config.yml --seed 42

Probability-based variation:

The probability field (0.0-1.0) controls how often a loop plays each cycle. Lower values create sparser, more varied textures. Silent cycles maintain timing so loops stay in sync. Use --seed for reproducible sessions.

loops:
  - file: audio/rain.wav
    volume: 0.7
    loop_length: 10.0
    probability: 1.0      # always plays (default)

  - file: audio/birds.flac
    volume: 0.6
    loop_length: 8.0
    probability: 0.5      # plays ~50% of cycles

  - file: audio/chimes.wav
    volume: 0.3
    loop_length: 15.0
    probability: 0.3      # plays ~30% of cycles (sparse)

Drone loops (continuous playback):

Set type: drone for loops that should play continuously without stagger or cycle boundaries. Drones wrap seamlessly at buffer end and work with probability for fade-in/out variation.

loops:
  # Regular loop with fade-out
  - file: audio/rain.wav
    volume: 0.7
    loop_length: 10.0
    fade_out: 2.0

  # Drone - continuous, no stagger
  - file: audio/pad.wav
    name: "Ambient Pad"
    type: drone
    volume: 0.4
    probability: 0.8
    fade_out: 3.0

Export to WAV file:

ambientmachine config.yml --export output.wav --duration 1h

Export to FLAC:

ambientmachine config.yml --export output.flac --duration 30m

Export with real-time monitoring:

ambientmachine config.yml --export output.wav --duration 1h --monitor

Multi-track export (one file per loop for DAW mixing):

ambientmachine config.yml --export output/ --multi-track --name session --duration 1h

Multi-track export as FLAC:

ambientmachine config.yml --export output/ --multi-track --name session --format flac --duration 30m

Multi-track export with monitoring:

ambientmachine config.yml --export output/ --multi-track --name session --duration 1h --monitor

Timed playback (auto-stop after duration):

ambientmachine config.yml --duration 1h

Verbose mode:

ambientmachine config.yml -v

Multi-Track Export

When --multi-track is enabled, --export specifies an output directory and --name provides a base filename. Each loop is written as a separate file, named from the loop's name field in the YAML config (sanitized and deduplicated).

For example, with a config containing loops named "Choir 01", "Choir 02", and "Choir 02":

ambientmachine config.yml --export stems/ --multi-track --name session --duration 1h

Produces:

stems/session-choir-01.wav
stems/session-choir-02.wav
stems/session-choir-02-2.wav

Individual track files do not have master volume applied, so they can be mixed freely in a DAW. The --format flag controls the output format (default: wav).

Configuration

See docs/config.md for the full configuration reference.

Supported Formats

• WAV
• MP3
• FLAC