> For the complete documentation index, see [llms.txt](https://parad0xlabs.gitbook.io/parad0xlabs-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://parad0xlabs.gitbook.io/parad0xlabs-docs/nebula-media-proof-carrying-media/how-it-works.md).

# How It Works

Nebula optimizes for one thing: the **smallest file at a quality you can prove**. It does that with scene-aware encoding, four codecs, and a measured quality proof on every output. The pipeline is **MIT-licensed and open** ([`Parad0x-Labs/nebula-media`](https://github.com/Parad0x-Labs/nebula-media)).

***

## Scene-aware, per-zone bitrate

Most encoders spend bits evenly. Nebula first detects **scene boundaries**, then allocates bitrate per zone — calm scenes get fewer bits, complex motion gets more. Quality lands where the eye actually notices it, which is most of the quality-per-bit win.

***

## Four codecs, auto-selected

| Codec            | Why                                                                  |
| ---------------- | -------------------------------------------------------------------- |
| **x265 (HEVC)**  | Battle-tested, the widest device/browser support — the safe default. |
| **SVT-AV1**      | Modern, royalty-free, meaningfully smaller at equal quality.         |
| **VVC (H.266)**  | Newest standard, the smallest files where it's supported.            |
| **VideoToolbox** | Apple hardware path — real-time encoding on Apple Silicon.           |

Nebula auto-selects the codec and preset for the best quality-per-bit — or you force one. (An explicit `--target-vmaf` is informational today; rate-control to *hit* a target number isn't implemented yet.)

```bash
# balanced mode — auto-selects codec, measures VMAF, emits a proof hash
python -m nebula.encoder input.mp4

# force a codec / mode, or skip VMAF for speed
python -m nebula.encoder input.mp4 --encoder vvc --mode safe
python -m nebula.encoder input.mp4 --encoder videotoolbox --mode balanced   # hardware, real-time
python -m nebula.encoder input.mp4 --no-vmaf
```

```json
{
  "output": "input_nebula.mp4",
  "vmaf": 95.44,
  "vmaf_p1": 93.07,
  "ratio": 0.191,
  "encoder": "x265",
  "proof_hash": "57b8f969f37c3a6d…"
}
```

(`ratio` is output ÷ input — `0.191` means the file came out \~81% smaller, at VMAF 95.4 with a worst-frame floor of 93.1. Content-dependent — your media will differ.)

***

## The quality proof (this is the differentiator)

Nebula measures every output with **VMAF**, and reports two numbers, not one:

* **VMAF mean** — overall perceptual quality (0–100).
* **VMAF 1st-percentile (`vmaf_p1`)** — the *worst \~1% of frames*. This is what stops "great average, one ugly scene" from slipping through — you bound the floor, not just the average.

Those measurements plus the source/output fingerprints fold into a **`proof_hash`** (SHA-256) — computed locally on every encode, and anchored on Solana when a keypair is configured. That receipt is what lets a platform prove an SLA, or a creator prove a file is the authentic derivative — the same proof-carrying pattern Liquefy and OpenClaw use, applied to media.

***

## Limits

* **Alpha.** The pipeline is open and runnable; it's early. Treat the example numbers as illustrations, not guarantees.
* **Numbers are content-dependent.** A talking-head clip and a fireworks display compress nothing alike.
* VMAF is a *perceptual* metric — an excellent proxy, not a guarantee every human agrees on every frame. The `vmaf_p1` report exists precisely to keep that grounded.
* **Open-core, MIT.** The code is MIT; a managed/hosted tier exists for scale and operational guarantees — it adds hosting, not closed code.

***

**Next:** [**Monetize**](/parad0xlabs-docs/nebula-media-proof-carrying-media/make-money.md) **— where quality-per-bit turns into a smaller bandwidth bill.**


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://parad0xlabs.gitbook.io/parad0xlabs-docs/nebula-media-proof-carrying-media/how-it-works.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.