From 64024630d74a15ace8395c23a3ed2fa58e87fdb1 Mon Sep 17 00:00:00 2001
From: Hugoved <hugovedlife@gmail.com>
Date: Mon, 11 May 2026 09:51:52 +0200
Subject: [PATCH] Update README.md

---
 README.md | 160 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 159 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 2e84433..6fd43a6 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,160 @@
 # pyav1plus
-pyav1plus is a Python-based tool for extracting HDR10+ dynamic metadata from AV1 video streams, with support for IVF, MP4/fMP4, and MKV containers.
+
+**pyav1plus** is a Python-based tool for extracting **HDR10+ dynamic metadata** from **AV1** video streams.  
+The project supports multiple AV1 container formats, including **IVF**, **MP4/fMP4**, and **Matroska (MKV)**, with direct parsing of AV1 OBUs and HDR10+ ITU-T T.35 metadata.
+
+---
+
+## Features
+
+* Support for **AV1 IVF**
+* Support for **AV1 MP4**
+* Support for **AV1 fragmented MP4 (fMP4)**
+* Support for **AV1 Matroska (MKV)**
+* Direct parsing of **AV1 OBU metadata**
+* Extraction of **HDR10+ ITU-T T.35 metadata**
+* Automatic generation of classic HDR10+ JSON
+* Stream-oriented parsing for large files
+* Automatic input format detection
+
+---
+
+## Requirements
+
+* Python 3.9 or higher
+
+No external binaries or dependencies are required.
+
+---
+
+## Usage
+
+Basic:
+
+```bash
+python pyav1plus.py input.ivf
+```
+
+```bash
+python pyav1plus.py input.mp4
+```
+
+```bash
+python pyav1plus.py input.mkv
+```
+
+Custom output path:
+
+```bash
+python pyav1plus.py input.mp4 -o metadata.json
+```
+
+---
+
+## Supported Formats
+
+| Format | Supported |
+| --- | --- |
+| AV1 IVF | Yes |
+| AV1 MP4 | Yes |
+| AV1 Fragmented MP4 | Yes |
+| AV1 MKV | Yes |
+
+---
+
+## Output
+
+The tool generates a classic HDR10+ JSON structure containing:
+
+* `JSONInfo`
+* `SceneInfo`
+* `SceneInfoSummary`
+* `ToolInfo`
+
+---
+
+## Example
+
+Input:
+
+```bash
+python pyav1plus.py movie.mkv
+```
+
+Output:
+
+```text
+Input format: MKV
+Scanning AV1 samples for HDR10+ metadata...
+[■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■] 100.00%
+
+Reordering metadata... Done.
+Reading parsed dynamic metadata... Done.
+Generating and writing metadata to JSON file...
+Generating and writing metadata to JSON file... Done.
+Frames written: 209557
+Output: movie.json
+```
+
+---
+
+## Script Example
+
+```python
+import json
+import sys
+import pyav1plus
+
+input_file = "input.mkv"
+output_file = "metadata.json"
+
+try:
+    input_format = pyav1plus.detect_input_format(input_file)
+
+    if input_format == "ivf":
+        iterator = pyav1plus.iter_ivf_samples(input_file)
+    elif input_format == "mp4":
+        iterator = pyav1plus.iter_mp4_samples(input_file)
+    elif input_format == "mkv":
+        iterator = pyav1plus.iter_mkv_samples(input_file)
+    else:
+        raise ValueError("Unsupported input format")
+
+    t35_by_frame = []
+
+    for index, payload, total in iterator:
+        t35 = pyav1plus.extract_t35_from_av1_sample(payload, index)
+        t35_by_frame.append(t35)
+
+    metadata = pyav1plus.build_classic_json_from_t35_list(t35_by_frame)
+
+    with open(output_file, "w", encoding="utf-8") as file:
+        json.dump(metadata, file, indent=2)
+
+except KeyboardInterrupt:
+    raise SystemExit(130)
+except Exception as error:
+    print(f"Extraction failed: {error}", file=sys.stderr)
+    raise SystemExit(1)
+```
+
+---
+
+## Notes
+
+This project focuses specifically on **AV1 HDR10+ metadata extraction**.  
+The parser operates directly on AV1 bitstreams and container structures without relying on external multimedia frameworks.
+
+Different MP4 layouts are supported, including fragmented and non-fragmented variants commonly found in streaming workflows.
+
+---
+
+## Issues and Support
+
+If you encounter any issues, please open an issue in the repository.
+
+---
+
+## Acknowledgements
+
+Thank you for your interest in this project.