emwy is a command-line video editor for turning long, raw recordings into clean, watchable videos using a simple YAML project file. It is designed for lecture capture, problem-solving videos, and other educational or technical recordings where speed, repeatability, and precision matter.

Internally, emwy compiles timeline segments into a render plan, renders A/V segments with FFmpeg/SoX, and concatenates them with mkvmerge. MLT export is optional for interoperability.

emwy is pronounced as one syllable, like a child trying to say "Emily" but replacing the "L" sound with a "W": em-wee.

pip install emwy

You need at least:

• ffmpeg
• sox
• mkvmerge (mkvtoolnix)
• mediainfo
• mlt / melt (optional, for MLT export)

See docs/INSTALL.md for full platform-specific instructions.

Install Python dependencies with:

pip install -r pip_requirements.txt

Save as example.emwy.yaml (recommended extension for v2):

emwy: 2

profile:
  fps: "30000/1001"
  resolution: [1920, 1080]
  audio: {sample_rate: 48000, channels: stereo}

assets:
  video:
    lecture: {file: lecture.mp4}

timeline:
  segments:
    - source: {asset: lecture, in: "00:10.0", out: "05:00.0"}

output:
  file: lecture_trimmed.mkv

emwy example.emwy.yaml

lecture_trimmed.mkv

• Trimming lectures and screen recordings
• Speeding up silent or repetitive sections
• Adding chapter cards and YouTube chapters
• Simple overlays like picture-in-picture or slides
• Audio cleanup such as normalization and noise reduction
• Fully scriptable, reproducible edits

• Complex motion graphics
• Color grading
• Visual effects or animation-heavy edits
• Replacing full GUI NLEs for cinematic workflows

The pipeline is intentionally simple:

.emwy.yaml
   ->
validated project graph
   ->
compiled render plan
   ->
per-segment A/V renders
   ->
concatenated output

MLT XML can be exported and inspected, which makes emwy suitable for headless systems, servers, and CI pipelines.

Deeper documentation lives in the docs/ directory:

• docs/INSTALL.md System dependencies, platform notes, and install verification.

• docs/FORMAT.md Project file format, time rules, and minimal and complete examples.

• docs/COOKBOOK.md Common editing recipes and reusable patterns.

• docs/CLI.md Command-line options, validation, dry runs, and logging.

• docs/TOOLS.md Helper scripts in tools/ and how to use them.

• docs/SHOTCUT.md Shotcut-compatible export mode and round-tripping notes.

• docs/DEBUGGING.md Common errors, diagnostics, and media inspection tips.

• docs/FAQ.md Design decisions, limitations, and common questions.

• docs/CHANGELOG.md User-facing changes and format migration notes.

• docs/DEVELOPMENT.md Developer setup, tests, and contribution guidelines.

• docs/CODE_ARCHITECTURE.md High-level code structure and module responsibilities.

Optional planning and policy documents:

• docs/ROADMAP.md
• docs/SECURITY.md
• AGENTS.md

• OS: tested primarily on Linux
• Python: 3.8+
• Render engine: FFmpeg/SoX + mkvmerge (MLT optional for export)

emwy can export Shotcut-compatible MLT XML so Shotcut opens the project as a normal editable timeline. See docs/SHOTCUT.md for details and limitations.

• Follow docs/DEVELOPMENT.md and docs/PYTHON_STYLE.md for coding conventions.
• Use pip install -r pip_requirements.txt in a virtual environment to sync tooling.
• Check AGENTS.md to understand who maintains each subsystem.
• Review docs/CHANGELOG.md before shipping user-facing changes.

• Current format version: emwy YAML v2
• The format is still evolving
• Validation is strict by default, with warnings where safe

The authoritative specification is in docs/FORMAT.md.

To export MLT XML for inspection or melt rendering:

python3 -m emwylib.exporters.mlt -y example.emwy.yaml -o example.mlt

See LICENSE.

emwy builds on excellent upstream tools:

• FFmpeg
• SoX
• MediaInfo
• mkvmerge (mkvtoolnix)
• MLT Multimedia Framework (export)