From 28597ea93ce2a191905b6ab3d330b9500e716b9c Mon Sep 17 00:00:00 2001
From: Vanilagy <1696106+Vanilagy@users.noreply.github.com>
Date: Mon, 16 Jun 2025 20:51:58 +0200
Subject: [PATCH] Yapperino
---
docs/.vitepress/config.mts | 2 +
docs/guide/installation.md | 33 ++++++++++++++
docs/guide/introduction.md | 83 ++++++++++++++++++++++++----------
docs/guide/quick-start.md | 31 +++++++++++++
src/conversion.ts | 2 +-
src/isobmff/isobmff-boxes.ts | 6 +--
src/matroska/matroska-muxer.ts | 2 +-
7 files changed, 129 insertions(+), 30 deletions(-)
create mode 100644 docs/guide/installation.md
create mode 100644 docs/guide/quick-start.md
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 2f1e2ff..d993ca5 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -18,6 +18,8 @@ export default withMermaid({
text: 'Getting started',
items: [
{ text: 'Introduction', link: '/guide/introduction' },
+ { text: 'Installation', link: '/guide/installation' },
+ { text: 'Quick start', link: '/guide/quick-start' },
],
},
{
diff --git a/docs/guide/installation.md b/docs/guide/installation.md
new file mode 100644
index 0000000..4ba90b2
--- /dev/null
+++ b/docs/guide/installation.md
@@ -0,0 +1,33 @@
+# Installation
+
+Install Mediabunny using your favorite package manager:
+
+::: code-group
+```bash [npm]
+npm install mediabunny
+```
+```bash [yarn]
+yarn add mediabunny
+```
+```bash [pnpm]
+pnpm add mediabunny
+```
+```bash [bun]
+bun add mediabunny
+```
+:::
+
+Then, simply import it like this:
+```ts
+import { ... } from 'mediabunny'; // ESM
+const { ... } = require('mediabunny'); // or CommonJS
+```
+
+ESM is prefered because it gives you tree shaking.
+
+You can also just include the library using a script tag in your HTML:
+```html
+
+```
+
+You can download the built distribution file from the [releases page](https://github.com/Vanilagy/mediabunny/releases).
\ No newline at end of file
diff --git a/docs/guide/introduction.md b/docs/guide/introduction.md
index bb71c21..428aeb3 100644
--- a/docs/guide/introduction.md
+++ b/docs/guide/introduction.md
@@ -1,31 +1,64 @@
# Introduction
-Install Mediabunny using your favorite package manager:
+Mediabunny is a JavaScript library for reading, writing, and converting media files (like MP4 or WebM), directly in the browser. It aims to be a complete toolkit for doing high-performance media operations on the web. It's written from scratch in pure TypeScript, has zero dependencies, and is extremely tree-shakable, meaning you only include what you use. You can think of it like [FFmpeg](https://ffmpeg.org/), but built for the web.
-::: code-group
-```bash [npm]
-npm install mediabunny
-```
-```bash [yarn]
-yarn add mediabunny
-```
-```bash [pnpm]
-pnpm add mediabunny
-```
-```bash [bun]
-bun add mediabunny
-```
-:::
+## Features
-Both ESM and CommonJS are supported:
-```ts
-import * as Mediabunny from 'mediabunny';
-const Mediabunny = require('mediabunny');
-```
+Here's a long list of stuff this library does:
-Alternativly, you can simply include the library using a script tag in your HTML:
-```html
-
-```
+- Reading metadata from media files
+- Extracting media data from media files
+- Creating new media files
+- Converting media files
+- Hardware-accelerated decoding & encoding (via the WebCodecs API)
+- Support for multiple video, audio and subtitle tracks
+- Support for many container formats (.mp4, .mov, .webm, .mkv, .mp3, .wav, .ogg)
+- Support for 25 different codecs
+- Lazy, optimized, on-demand file reading
+- Input and output streaming, arbitrary file size support
+- File location independence (memory, disk, network, ...)
+- Utilities for compression, resizing, rotation, resampling, trimming
+- Microsecond-accurate reading and writing precision
+- Efficient seeking through time
+- Pipelined design for efficient hardware usage and automatic backpressure
+- Custom encoder & decoder support for polyfilling
+- Low- & high-level abstractions for different use cases
+- Performant everything
+- Node.js support
-You can download the built distribution file from the [releases page](https://github.com/Vanilagy/mp4-muxer/releases).
\ No newline at end of file
+...and there's probably more.
+
+## Use cases
+
+Mediabunny is a general-purpose toolkit and can be used in infinitely many ways. But, here are a few ideas:
+
+- File conversion & compression
+- Displaying file metadata (duration, dimensions, ...)
+- Extracting thumbnails
+- Creating videos in the browser
+- Building a video editor
+- Live recording & streaming
+
+Check out the [Examples](/examples) page for demo implementations of many of these ideas!
+
+## Motivation
+
+Mediabunny is the evolution of my previous libraries, [mp4-muxer](https://github.com/Vanilagy/mp4-muxer) and [webm-muxer](https://github.com/Vanilagy/webm-muxer), which were both created due to the advent of the WebCodecs API. While they fulfilled their job just fine, I saw a few painpoints:
+- Lots of duplicated code between the two libraries, otherwise very similar API.
+- No help with the difficulties of navigating the WebCodecs API & related browser APIs.
+- "mp4-demuxer when??"
+
+This library is the result of unifying these libraries into one, solving all the above issues, and expanding the scope. Now:
+- Changing the output file format is a single-line change; the rest of the API is identical.
+- Lots of abstractions on top of the WebCodecs API & browser APIs are provided.
+- mp4-demuxer now.
+
+Due to tree shaking, if you only need an MP4 or WebM muxer, this library's bundle size will still be very small.
+
+## Technical overview
+
+At its core, Mediabunny is a collection of multiplexers and demultiplexers, one of each for every container format. Demultiplexers stream data from *sources*, while multiplexers stream data to *targets*. Every demultiplexer is capable of extracting file metadata as well as compressed media data, while multiplexers write metadata and encoded media data into a new file.
+
+Mediabunny then provides several wrappers around the WebCodecs API to simplify usage: for reading, it creates decoders with the correct codec configuration and efficiently decodes media data in a pipelined way. For writing, it figures out the necessary codec configuration and sets up encoders which are then used to encode raw media data, while respecting the backpressure applied by the encoder. Extracting the right decoder configuration from a media file can be tricky and sometimes involves diving into encoded media packet bitstreams.
+
+The conversion abstraction is built on top of Mediabunny's reading and writing primitives and combines them both in a heavily-pipelined way, making sure reading and writing happen in lockstep. It also consists of a lot of conditional logic probing output track compatibility, decoding support, and finding encodable codec configurations. It makes use of the Canvas API for video processing operations, and uses a custom implementation for audio resampling and up/downmixing.
\ No newline at end of file
diff --git a/docs/guide/quick-start.md b/docs/guide/quick-start.md
new file mode 100644
index 0000000..3f6d8d4
--- /dev/null
+++ b/docs/guide/quick-start.md
@@ -0,0 +1,31 @@
+# Quick start
+
+This page is a collection of short code snippets to showcase the most common operations you may use this library for.
+
+## Reading file metadata
+
+```ts
+import { Input, ALL_FORMATS, BlobSource } from 'mediabunny';
+
+const input = new Input({
+ formats: ALL_FORMATS,
+ source: new BlobSource(file), // Assuming a File instance
+});
+
+const duration = await input.computeDuration(); // in seconds
+
+const videoTrack = await input.getPrimaryVideoTrack();
+if (videoTrack) {
+ const width = videoTrack.displayWidth;
+ const height = videoTrack.displayHeight;
+ const rotation = videoTrack.rotation; // in degrees clockwise
+}
+
+const audioTrack = await input.getPrimaryAudioTrack();
+if (audioTrack) {
+ const numberOfChannels = audioTrack.numberOfChannels;
+ const sampleRate = audioTrack.sampleRate; // in Hz
+}
+```
+
+## Reading media data
\ No newline at end of file
diff --git a/src/conversion.ts b/src/conversion.ts
index 1ef6efe..552f784 100644
--- a/src/conversion.ts
+++ b/src/conversion.ts
@@ -809,7 +809,7 @@ export class Conversion {
});
const sink = new AudioSampleSink(track);
- const iterator = sink.samples(this._startTimestamp, this._endTimestamp); // Todo make sure timestamps work
+ const iterator = sink.samples(this._startTimestamp, this._endTimestamp);
for await (const sample of iterator) {
if (this._synchronizer.shouldWait(track.id, sample.timestamp)) {
diff --git a/src/isobmff/isobmff-boxes.ts b/src/isobmff/isobmff-boxes.ts
index 7fc519d..4a77b60 100644
--- a/src/isobmff/isobmff-boxes.ts
+++ b/src/isobmff/isobmff-boxes.ts
@@ -458,9 +458,9 @@ const TRACK_TYPE_TO_COMPONENT_SUBTYPE: Record
};
const TRACK_TYPE_TO_HANDLER_NAME: Record = {
- video: 'VideoHandler',
- audio: 'SoundHandler',
- subtitle: 'TextHandler',
+ video: 'MediabunnyVideoHandler',
+ audio: 'MediabunnySoundHandler',
+ subtitle: 'MediabunnyTextHandler',
};
/** Handler Reference Box: Specifies the media handler component that is to be used to interpret the media's data. */
diff --git a/src/matroska/matroska-muxer.ts b/src/matroska/matroska-muxer.ts
index f300e61..9d0b03f 100644
--- a/src/matroska/matroska-muxer.ts
+++ b/src/matroska/matroska-muxer.ts
@@ -53,7 +53,7 @@ import { parseOpusIdentificationHeader } from '../codec-data';
const MIN_CLUSTER_TIMESTAMP_MS = -(2 ** 15);
const MAX_CLUSTER_TIMESTAMP_MS = 2 ** 15 - 1;
-const APP_NAME = 'https://github.com/Vanilagy/webm-muxer'; // TODO
+const APP_NAME = 'https://github.com/Vanilagy/mediabunny';
const SEGMENT_SIZE_BYTES = 6;
const CLUSTER_SIZE_BYTES = 5;