Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
28 changes: 14 additions & 14 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,26 +9,26 @@ without copying either interface or promising feature parity.
## Source of truth and context loading

For mutable facts, use this order: **code and relevant tests → accepted ADRs → dated
benchmark/workload evidence → implementation plan → specialized Docs → this guide**.
benchmark/workload evidence → implementation plan → specialized docs → this guide**.
An ADR records a decision, not proof that it shipped. Research is provisional. Resolve
conflicts by checking current code, tests and dated evidence, then correct the stale doc.

Load context progressively: this guide → one relevant skill if useful → the relevant
[implementation milestone](Docs/implementation-plan.md) and [next step](Docs/implementation-plan-next-step.md)
→ its [ADR](Docs/adr/README.md) → affected source/tests → evidence. Expand only when the
question requires it. Use [UI design](Docs/ui-design.md) for UX,
[format architecture](Docs/format-architecture.md) and [interop matrix](Docs/interop.md)
for formats, and [QA](Docs/implementation-plan-qa.md) for validation. [CONTRIBUTING.md](CONTRIBUTING.md)
[implementation milestone](docs/implementation-plan.md) and [next step](docs/implementation-plan-next-step.md)
→ its [ADR](docs/adr/README.md) → affected source/tests → evidence. Expand only when the
question requires it. Use [UI design](docs/ui-design.md) for UX,
[format architecture](docs/format-architecture.md) and [interop matrix](docs/interop.md)
for formats, and [QA](docs/implementation-plan-qa.md) for validation. [CONTRIBUTING.md](CONTRIBUTING.md)
contains build commands and contribution process; `make help` lists current targets.

## Facts, goals, preferences and evidence

**Facts** are checked in code: the app uses C++23, Qt Quick/QML, FFmpeg, Vulkan and
PipeWire; inspect current implementations before describing a path. **Goals** include
GPU-native export, clearer Session ownership and more explicit QML composition; the
[M12 plan](Docs/implementation-plan-m12-gpu-export-architecture.md) marks these as planned.
[M12 plan](docs/implementation-plan-m12-gpu-export-architecture.md) marks these as planned.
**Maintainer preferences** below guide choices but may be challenged by code or evidence.
**Evidence** lives in `Docs/Research/evidence/`, tests and workload protocols, not here.
**Evidence** lives in `docs/Research/evidence/`, tests and workload protocols, not here.

Use status terms precisely: *implemented* = connected code; *tested* = relevant test;
*measured* = repeatable benchmark; *validated* = declared workload plus recorded result;
Expand Down Expand Up @@ -81,31 +81,31 @@ scope.
| PR, issue, release or repository health | the matching focused audit/resolution/release skill only |

Do not invoke several reviewers for a routine edit. Skills supply reusable method, while
Docs and code supply OmaMovie's current decisions and facts.
The docs and code supply OmaMovie's current decisions and facts.

## Scope and completion

Build the committed workflow before adding effect categories or competitor parity. The
[v0.1 release decision](Docs/implementation-plan-milestone-overview.md) covers only its
validated Intel/software scope; the [first-opening tour](Docs/implementation-plan-v1-onboarding.md)
[v0.1 release decision](docs/implementation-plan-milestone-overview.md) covers only its
validated Intel/software scope; the [first-opening tour](docs/implementation-plan-v1-onboarding.md)
and bundled editable demo are in v0.1, while contextual tooltip and novice task gates
remain open. AMD/NVIDIA, full HDR and other desired capabilities require their
own evidence. Do not turn aesthetic refactoring into a release gate.

A change is done when its actual behavior and error/fallback path have proportional
checks, affected integration/workload gates pass, documentation states the resulting
scope accurately, and the report names any unverified claim. See
[CONTRIBUTING.md](CONTRIBUTING.md) for commands and [milestone rules](Docs/implementation-plan-milestones.md)
[CONTRIBUTING.md](CONTRIBUTING.md) for commands and [milestone rules](docs/implementation-plan-milestones.md)
for release criteria.

## Older section references

Older source comments cite sections of the former long guide. Resolve them through the
sources here: §3–5 build/dependencies → `CONTRIBUTING.md`, ADR-0001/0018 and CMake;
§6 time → ADR-0002; §7–9 GPU/media/compositor → ADR-0004/0005/0006 and M2/M3/M12;
§10–11 timeline/UI → M5/M6 and `Docs/ui-design.md`; §12–13 audio/concurrency →
§10–11 timeline/UI → M5/M6 and `docs/ui-design.md`; §12–13 audio/concurrency →
ADR-0003/0020 and M4; §14–15 project/cache → ADR-0007/0009 and M7;
§16 interop → ADR-0008 and `Docs/interop.md`; §18–19 parser/errors → QA and code;
§16 interop → ADR-0008 and `docs/interop.md`; §18–19 parser/errors → QA and code;
§20–26 agent/process/performance/tests → ADR index, evidence, milestones and
`CONTRIBUTING.md`. Update a touched comment to its direct source rather than extending
this compatibility map.
10 changes: 5 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,11 +26,11 @@ make fuzz
`scripts/check-includes.sh` verifies dependency boundaries not expressed by CMake.
`scripts/package-check.sh` exercises the package in disposable containers. Benchmark
and spike commands, their fixtures and measurement protocols live beside each task in
`Docs/Research/evidence/`, `Docs/spikes/` and `tools/bench/`; run only the relevant ones.
`docs/Research/evidence/`, `docs/spikes/` and `tools/bench/`; run only the relevant ones.

Commit messages use Conventional Commits in English, with an imperative description
under 100 characters. Check a range with `scripts/check-commits.sh`. Do not create a
release tag as part of normal implementation work; the [release plan](Docs/implementation-plan-m10-validation.md)
release tag as part of normal implementation work; the [release plan](docs/implementation-plan-m10-validation.md)
and CI define its separate gates.

## Change protocol
Expand All @@ -47,6 +47,6 @@ and CI define its separate gates.
5. Report what ran and what remains unverified. Do not silently ignore a relevant warning
or failure.

Key sources: [implementation plan](Docs/implementation-plan.md), [ADR index](Docs/adr/README.md),
[UI design](Docs/ui-design.md), [format architecture](Docs/format-architecture.md),
[interop support levels](Docs/interop.md), and [QA plan](Docs/implementation-plan-qa.md).
Key sources: [implementation plan](docs/implementation-plan.md), [ADR index](docs/adr/README.md),
[UI design](docs/ui-design.md), [format architecture](docs/format-architecture.md),
[interop support levels](docs/interop.md), and [QA plan](docs/implementation-plan-qa.md).
61 changes: 27 additions & 34 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,63 +1,56 @@
# OmaMovie

<img src="Docs/media/omamovie-logo.svg" width="360" alt="OmaMovie logo: a play button over three timeline clips">
<img src="docs/media/omamovie-logo.svg" width="360" alt="OmaMovie logo: a play button over three timeline clips">

OmaMovie is a video editor under development for Omarchy. Its current editor shell lets you import local videos and pictures, arrange clips on a timeline, preview the result, and adjust clip audio. It saves and opens projects and exports MP4, Matroska, or WebM movies.
OmaMovie is a video editor for Omarchy and current Arch Linux. It is for people who want to assemble local video, audio and pictures into a movie, check the edit with sound, save their work and export a shareable file. The first public release candidate targets x86_64; [Intel Iris Xe and software rendering are the validated configurations](#release-candidate-scope).

![OmaMovie editor showing a preview, video clips, and an audio lane on the timeline](Docs/media/editor-test.webp)
![The OmaMovie editor with a video preview, two clips and an audio track on the timeline](docs/media/editor-test.webp)

*The running editor with synthetic test clips. The preview and timeline are captured from the GUI smoke test.*
*The editor running a synthetic test edit. The screenshot comes from the GUI smoke test.*

## Try the editor
## Make your first edit

On an Omarchy or current Arch Linux system, from this repository:
On Omarchy or a current Arch Linux system, clone this repository and run:

```sh
make deps
make run-gui
```

`make deps` installs the packages declared in [PKGBUILD](PKGBUILD) using `pacman` and may request sudo. `make run-gui` builds and opens the Qt Quick editor.
`make deps` installs the dependencies in [PKGBUILD](PKGBUILD) through `pacman` and may request sudo. `make run-gui` builds and opens the editor. To install a system package instead, run `makepkg -si` from the repository root.

For a first edit:
The first-opening tour introduces the controls and opens a bundled, editable three-shot demo. You can use it to try an edit without finding media first:

1. Choose **New project**, then **Import** (`Ctrl+I`). Files imported while the timeline is empty are added to the storyline automatically. Once it has clips, new imports stay in the media library until you place them.
2. Select a library item and use **Add** (`E`) to append it. To use only part of it, open the source viewer (`Shift+O`), set In (`I`) and Out (`O`), then use **Add**. Escape returns to the sequence viewer.
3. Play or pause with Space, split at the playhead with `Ctrl+B`, and undo with `Ctrl+Z`. Save with `Ctrl+S` and export with `Ctrl+E`.
1. Play the demo with Space. Select a clip and move the playhead to the cut you want to change.
2. Split with `Ctrl+B`, then undo with `Ctrl+Z` if needed. Open the Command Palette with `Ctrl+K` to find actions and their shortcuts.
3. Save your copy as a `.omamovie` project with `Ctrl+S`. Export a movie with `Ctrl+E`, then choose a profile supported by your installed FFmpeg build.

You can also open a file directly:
For your own footage, start a **New project** and choose **Import** (`Ctrl+I`). Files imported into an empty timeline are added to the storyline. Later imports remain in the media library until you select one and use **Add** (`E`). In the source viewer (`Shift+O`), mark In (`I`) and Out (`O`) before adding a shorter range. Escape returns to the sequence viewer. The original media stays on disk and is not modified.

```sh
make run-gui GUI_FILE=/path/to/video.mp4
```

The imported media stays on disk and is never modified. Projects are saved as `.omamovie` files and can be reopened with `Ctrl+O`. `Ctrl+K` opens the command palette, which lists every action and lets you change its shortcut. `Ctrl+E` offers the output formats supported by the installed FFmpeg build: MP4 (H.264/AAC), Matroska (H.264/AAC or HEVC/AAC), and WebM (VP9/Vorbis). H.264 can use the GPU encoder on validated Intel hardware (VA-API), with a software fallback. Other profiles use software encoders. All outputs use the project's size and frame rate.
## What you can do

## What works today
- Arrange clips with append, insert, overwrite, trim, split, delete and ripple edits; undo and redo the changes.
- Preview the sequence with sound, and adjust clip gain, fades and mute.
- Add titles, looks and transitions, then export MP4, Matroska or WebM using the available profiles.
- Save and reopen `.omamovie` projects. If a source file has moved, the editor keeps its missing reference so you can locate it.
- Import documented subsets of OTIO, FCPXML, EDL and MLT projects. See the [interop matrix](docs/interop.md) before using another editor's project as the source of an edit.

- Import and inspect local video, audio and still image files through FFmpeg. Import checks that the chosen video and audio streams can produce an initial frame or samples; later damage in a file may still cause a decode error.
- Append, insert, overwrite, split, trim, delete, and ripple edit clips with undo and redo.
- Preview the timeline with Vulkan compositing and audio clock playback; adjust clip gain, fades, and mute.
- Use visible transport and edit controls, or their keyboard shortcuts, in the editor shell.
## Install and release files

The viewer decodes in hardware on Intel (VA-API) and in software elsewhere; `OMA_PREVIEW_HARDWARE=0` forces software. The app has bounded OTIO, FCPXML, EDL and MLT import paths. See the [interop matrix](Docs/interop.md) for implemented subsets and evidence gaps; these are not general compatibility claims for every project made by those editors.
The [GitHub Releases page](https://github.com/KitsuneForgering/OmaMovie/releases) provides release candidates, source archives and checksums. The x86_64 Linux application archive contains the installed `usr/` tree; it uses system Qt, FFmpeg, Vulkan and other [package dependencies](PKGBUILD), so it is not a self-contained application. On current Arch/Omarchy, `makepkg -si` builds, tests and installs the package, launcher, icon and `.omamovie` file association.

## Install
The editor follows the active Omarchy theme and font. If Omarchy's window opacity makes the video viewer translucent, see the [Hyprland window rule](docs/omarchy-window-rule.md).

`makepkg -si` builds the package from the [PKGBUILD](PKGBUILD) and installs `omamovie`, its launcher entry, icon and the `.omamovie` file type. The editor follows the active Omarchy theme and font while it runs.
## Release candidate scope

### Full opacity on Hyprland
This release candidate is intended for real edits and feedback. Intel Iris Xe and the software path have been validated; AMD, NVIDIA and hybrid GPU machines have not. The viewer uses Intel VA-API decoding when available and software decoding elsewhere. Set `OMA_PREVIEW_HARDWARE=0` to force software decoding. H.264 export can use the Intel GPU encoder, with a software fallback; other export profiles use software encoders. Export uses the project's frame size and rate.

Omarchy makes ordinary windows slightly translucent, which blends the wallpaper into the viewer. OmaMovie's window class (Wayland app_id) is `omamovie`. To keep it opaque, as Omarchy does for DaVinci Resolve, add this to `~/.config/hypr/windows.lua`:

```lua
o.window("^omamovie$", { tag = "-default-opacity", opacity = "1 1" })
```
Import checks that selected streams can decode an initial frame or samples, but damage later in a file may still cause a decode error. Cross-editor imports cover the subsets in the [interop matrix](docs/interop.md), rather than every project those editors can create. Export currently transfers rendered frames through host memory before encoding.

The package does not install this rule. It uses the Lua window-rule syntax of current Omarchy (`default/hypr/apps/davinci-resolve.lua`); older Hyprland configurations need their own syntax. Full opacity only stops the blending: it does not calibrate the display.
Please report unclear steps, incorrect output and crashes in [GitHub Issues](https://github.com/KitsuneForgering/OmaMovie/issues). Include your version, hardware, source format and steps to reproduce when possible.

## Build and development
## Development and documentation

Run `make test` for the library tests or `make help` for available targets. The [implementation plan](Docs/implementation-plan.md) tracks completed and pending milestones. [UI design](Docs/ui-design.md) describes the editor workflow. [Format boundaries](Docs/format-architecture.md), [contribution guide](CONTRIBUTING.md) and [agent guide](CLAUDE.md) point to architecture and development rules.
Run `make test` for the library tests or `make help` for available targets. The [implementation plan](docs/implementation-plan.md), [UI design](docs/ui-design.md), [format boundaries](docs/format-architecture.md), [contribution guide](CONTRIBUTING.md) and [agent guide](CLAUDE.md) provide deeper detail.

License: [MIT](LICENSE).
2 changes: 1 addition & 1 deletion apps/omamovie/qml/Main.qml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import QtQuick.Layouts
import QtQuick.Shapes
import OmaMovie 1.0

// Editor shell following Docs/ui-design.md: three fixed areas (library, viewer, timeline),
// Editor shell following docs/ui-design.md: three fixed areas (library, viewer, timeline),
// adjustments in a bar and drawer above the viewer, a transport, and every command
// registered once as an Action with its §8.1 shortcut.
ApplicationWindow {
Expand Down
2 changes: 1 addition & 1 deletion apps/omamovie/src/export_encoder.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
// The export's encoder as its own stage (code review part 5): the export job renders and reads
// back frame n+1 while this stage encodes frame n, so a frame costs about the slower of the two
// instead of their sum. Same-machine comparison:
// Docs/implementation-plan-cross-editor-benchmarks.md.
// docs/implementation-plan-cross-editor-benchmarks.md.
//
// Threading: one worker of its own pool (no ad hoc thread, §13) is the only user of the writer
// until finish() returns. Frames move in through a queue of two (backpressure); the producer
Expand Down
15 changes: 11 additions & 4 deletions apps/omamovie/src/gui_smoke.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@ class SmokeRun : public QObject {
const char* name;
std::function<bool()> ready;
std::function<void()> act;
qint64 timeout_ms = 8000;
};

SmokeRun(QGuiApplication& app, std::vector<Step> steps) : app_(app), steps_(std::move(steps)) {
Expand All @@ -96,7 +97,7 @@ class SmokeRun : public QObject {
if (index_ >= steps_.size()) return;
Step& step = steps_[index_];
if (!step.ready()) {
if (since_.elapsed() > 8000) {
if (since_.elapsed() > step.timeout_ms) {
std::printf("GUI smoke: FAIL (timed out at '%s')\n", step.name);
timer_.stop();
app_.exit(1);
Expand Down Expand Up @@ -476,7 +477,13 @@ int run_gui_smoke(const SmokeContext& context) {
{"sound import", after(100), [&] {
session.open(QStringLiteral("tests/fixtures/generated/tone_44100.wav"));
}},
{"audio lanes", [&] { return lane_count() == 1; }, [&] {
{"audio lanes", [&] {
if (lane_count() != 1) return false;
// Noise reduction and normalization below need the asynchronous waveform. Wait for
// that result explicitly instead of relying on earlier edit steps taking long enough.
const auto media = static_cast<std::uint64_t>(lane_clip(0).value("media").toDouble());
return qobject_cast<WaveformStore*>(session.waveforms())->get(media) != nullptr;
}, [&] {
// Appended sound lands on the first lane; a connected sound at an occupied time gets a
// new lane, and deleting the lane's only clip removes the lane again.
bool ok = std::abs(lane_clip(0).value("start").toDouble()) < 1e-9 &&
Expand Down Expand Up @@ -511,7 +518,7 @@ int run_gui_smoke(const SmokeContext& context) {
session.undo();
ok = ok && lane_count() == 1 && session.clips().front().toMap().value("hasAudio").toBool();
// Volume "More" on the sound: equalizer preset, noise reduction from the measured
// floor (the waveform is ready by now), and normalize (the quiet tone hits the
// floor (the waveform is ready), and normalize (the quiet tone hits the
// maximum volume).
session.selectClip(id);
session.setClipEq(-6, 3, 2);
Expand All @@ -529,7 +536,7 @@ int run_gui_smoke(const SmokeContext& context) {
window->setProperty("drawer", QStringLiteral("volume"));
window->setProperty("volumeMore", true);
r.lanes = ok;
}},
}, 30000},
{"volume more", after(300), [&] {
screenshot(window, "OMA_GUI_SMOKE_LANES_SCREENSHOT");
window->setProperty("drawer", QString());
Expand Down
2 changes: 1 addition & 1 deletion apps/omamovie/src/main.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -428,7 +428,7 @@ int main(int argc, char** argv) {
return session.exportedFile() == out ? 0 : 1;
}
if (timeline_audit) {
// M6 long-form gate (Docs/Research/long-form-editing.md): a storyline of N short clips
// M6 long-form gate (docs/Research/long-form-editing.md): a storyline of N short clips
// built with the timeline's own commands, saved with libs/project and opened in the
// editor; then routine edits, each timed from the call to the end of the next Qt frame
// that started after it (model rebuild, QML bindings and rendering included).
Expand Down
Loading
Loading