SoundWeave

A polished, terminal-native toolkit for cutting, joining, and layering audio with a local FFmpeg runtime.

SoundWeave turns everyday audio editing into a focused keyboard-and-mouse workflow. Browse your drives in a full-screen Textual interface, review the exact operation before it runs, watch progress in real time, and receive predictable MP3 output without installing FFmpeg system-wide.

What SoundWeave does

Script	Purpose	Result
split.py	Cut one audio file into fixed-length pieces	A numbered folder of MP3 chunks
join.py	Concatenate an ordered queue of files	One MP3 in a directory you choose
merge.py	Mix exactly two tracks at the same time	One layered stereo MP3

Use it for rehearsal recordings, lecture processing, podcast assembly, vocal-and-instrumental demos, stem preparation, and quick audio handoffs.

Why it feels different

• A modern terminal UI: Textual provides a full-screen interface with a file browser, forms, status panels, review states, buttons, and keyboard shortcuts.
• Safe by default: Operations are reviewed before execution. Existing generated files are never silently replaced.
• Format-friendly input: MP3, MPEG, AAC, OGG, and WAV files can be selected from the browser.
• Consistent output: Every workflow writes an MP3, using the local FFmpeg encoder.
• Mixed-source workflows: Join files from different supported input formats in sequence, or layer two different sources in a mix.
• Self-contained media runtime: The project uses imageio-ffmpeg to locate a project-local FFmpeg binary, so a machine-wide FFmpeg installation and PATH change are unnecessary.

Quick start

Requirements

• Windows is the primary supported platform.
• Python 3.11 or newer.
• uv for environment and dependency management.
• A terminal that supports normal keyboard input and Unicode.

You do not need to install FFmpeg separately. The Python dependency provides the executable used by SoundWeave.

Install

Clone the public repository and create the project environment:

git clone git@github.com:venkyjs/SoundWeave.git
cd SoundWeave
uv sync --dev

If your Python installation has certificate-chain issues while downloading packages, try:

uv sync --dev --system-certs

Launch a workflow

uv run python split.py
uv run python join.py
uv run python merge.py

You can also call the environment interpreter directly:

.\.venv\Scripts\python.exe split.py
.\.venv\Scripts\python.exe join.py
.\.venv\Scripts\python.exe merge.py

At startup each workflow verifies that its local FFmpeg runtime is available and that MP3 encoding support can be used.

Shared interface

Each application opens as a full-screen terminal program:

1. Choose a drive or root from the drive selector.
2. Browse folders in the directory tree.
3. Select a supported audio file.
4. Fill in the operation-specific fields.
5. Review the source, destination, and output names.
6. Start the operation and follow FFmpeg progress.
7. Cancel safely or quit when finished.

Useful controls

Action	Mouse	Keyboard
Move through the UI	Click a control	Arrow keys and Tab
Activate a focused control	Click	Enter
Quit	Click Quit	q or Esc
Cancel an active operation	Click Cancel	Ctrl+C
Confirm a review dialog	Click Continue	Focus the button and press Enter

The file browser accepts:

.mp3, .mpeg, .aac, .ogg, and .wav

Split audio into MP3 chunks

Run:

uv run python split.py

Select one file and provide a positive whole-number chunk length. The default is 30 seconds.

For an input named Raw-Audio.mp3, the output is created beside the source:

Raw-Audio_split/
  Raw-Audio_1.mp3
  Raw-Audio_2.mp3
  Raw-Audio_3.mp3
  ...

Split behavior:

• Numbering starts at 1.
• The final chunk may be shorter than the requested duration.
• Every chunk is encoded as MP3, regardless of the input format.
• The generated directory is named {input_file_name}_split.
• If an output folder already contains files with the same names, SoundWeave asks before replacing them.
• A cancelled or failed run cleans its staging files and preserves the previous completed output.

Join files in an exact sequence

Run:

uv run python join.py

Add files to the queue in the order they should play. The queue is intentionally explicit:

• Add the same file more than once when repetition is required.
• Use Move up / Move down or Ctrl+Up / Ctrl+Down to change order.
• Use Remove or Delete to remove the selected item.
• Use Clear to reset the queue.
• Choose the destination directory in the browser.
• Enter any output name; SoundWeave normalizes it to .mp3.

Joining is sequential concatenation. It does not add crossfades, silence, or overlap between files. This makes the output order easy to reason about and reproduce.

Merge two tracks on top of each other

Run:

uv run python merge.py

Choose two files and assign them to Track 1 and Track 2. This is designed for a vocal over drums, narration over music, a guide track over a backing track, or any other two-source layer.

The merge workflow:

1. Select a file in the browser.
2. Assign it to Track 1 with the button or key 1.
3. Select another file and assign it to Track 2 with the button or key 2.
4. Choose an output directory and name. The default name is merged.mp3.
5. Review the two sources and confirm.

The two audio streams are mixed simultaneously with FFmpeg's amix filter. The output uses the longer input duration, is encoded as a stereo MP3, and applies normalization to help prevent clipping when both tracks are loud.

A practical Meta SAM workflow

SoundWeave pairs naturally with Meta Segment Anything - audio editor.

Meta's audio segmentation editor can help isolate useful regions or sources from a recording. SoundWeave then handles the file operations around those isolated results:

1. Import a recording into the Meta SAM audio editor.
2. Isolate the vocal, drums, speech, ambience, or other region you need.
3. Export the isolated audio result.
4. Use split.py to create fixed-length MP3 pieces for review, annotation, or upload.
5. Use join.py to assemble selected pieces in a precise sequence.
6. Use merge.py to layer two exported results back together, such as isolated vocals over isolated drums.

In short, Meta SAM can help you isolate audio; SoundWeave helps you organize, cut, concatenate, and layer the resulting files. Check the Meta demo's own export and usage terms before using it for production or redistribution.

Output and safety model

SoundWeave keeps media work transactional:

flowchart LR
    A[Textual file browser] --> B[Validate paths and settings]
    B --> C[Probe the selected audio]
    C --> D[Run local FFmpeg]
    D --> E[Write to a staging location]
    E --> F[Review progress and result]
    F --> G[Commit final MP3 output]
    F --> H[Cancel or clean up staging files]

Loading

The implementation is designed around these guarantees:

• Paths and FFmpeg arguments are passed as structured subprocess arguments rather than shell command strings.
• Inputs, extensions, chunk lengths, queue size, and output names are validated before work begins.
• Existing generated outputs require an explicit confirmation.
• Failed or cancelled operations do not replace the last completed result.
• MP3 output uses the libmp3lame encoder with quality-oriented variable bitrate settings.
• Temporary files are cleaned up after cancellation or errors.

Troubleshooting

uv is not recognized

Install uv from its official installation instructions, reopen the terminal, and run uv sync --dev again.

Dependency or certificate errors

Use the system certificate store:

uv sync --dev --system-certs

FFmpeg setup fails

Make sure the environment was created successfully and that imageio-ffmpeg is installed:

uv sync --dev

SoundWeave deliberately uses the project-local FFmpeg runtime rather than requiring a separate system installation.

A file does not appear in the browser

Confirm that it uses one of the supported extensions, is readable by your Windows account, and contains an audio stream. Rename the extension only when the underlying file really matches that format.

The output duration is not exactly what I expected

Encoded audio can have small container and codec padding differences. For merge operations, the output duration follows the longer input by design. For split operations, the final piece is shorter whenever the source duration is not an exact multiple of the chunk length.

SoundWeave asks about replacement

This means the requested output name already exists. Confirm only when replacing that file is intentional; otherwise choose a different output name or destination.

Development

The repository is intentionally small and easy to inspect:

SoundWeave/
  split.py                  Split one file into numbered MP3 chunks
  join.py                   Concatenate an ordered queue
  merge.py                  Mix two tracks simultaneously
  audio_tools/
    media.py                FFmpeg command builders
    media_service.py        Probe, split, join, and merge operations
    models.py               Validated request and progress models
    paths.py                Path and output-name validation
    tui_common.py           Shared Textual browser helpers
    confirm.py              Review confirmation screen
  tests/                    Unit, integration, and Textual app tests
  pyproject.toml            Project metadata and dependencies
  uv.lock                   Reproducible dependency lockfile

Install development dependencies:

uv sync --dev

Run the test suite:

.\.venv\Scripts\python.exe -m pytest -q

Compile-check the Python modules:

.\.venv\Scripts\python.exe -m compileall split.py join.py merge.py audio_tools tests

The tests cover request validation, path safety, command construction, FFmpeg integration, transactional output behavior, cancellation, queue ordering, merge-slot assignment, and key Textual UI states.

Project

• Repository: github.com/venkyjs/SoundWeave
• License: no license file is currently included. Add a license before distributing the project or accepting external contributions under explicit terms.
• Status: actively evolving as a focused local audio utility.

Contributing

Issues and pull requests are welcome. When proposing a change:

1. Keep media operations deterministic and testable.
2. Preserve the review and no-silent-overwrite behavior.
3. Add or update tests for new FFmpeg commands and UI states.
4. Document new keyboard shortcuts and output conventions.
5. Keep platform-specific behavior explicit, especially around filesystem paths and FFmpeg discovery.