From 4e1d43a3b278991784a2b8ea5977a98f68d76680 Mon Sep 17 00:00:00 2001 From: Vanilagy <1696106+Vanilagy@users.noreply.github.com> Date: Sat, 28 Jun 2025 19:44:20 +0200 Subject: [PATCH] Write README --- README.md | 167 ++++++++++++++++++++++++++++++++++++- docs/guide/introduction.md | 4 +- 2 files changed, 168 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index f87f5c1..b7ebdd2 100644 --- a/README.md +++ b/README.md @@ -1 +1,166 @@ -# TODO \ No newline at end of file +# Mediabunny - JavaScript media toolkit + +[![](https://img.shields.io/npm/v/mediabunny)](https://www.npmjs.com/package/mediabunny) +[![](https://img.shields.io/bundlephobia/minzip/mediabunny)](https://bundlephobia.com/package/mediabunny) +[![](https://img.shields.io/npm/dm/mediabunny)](https://www.npmjs.com/package/mediabunny) + +
+ +
+ +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 high-performance media operations on the web. It's written from scratch in pure TypeScript, has zero dependencies, is very performant, and is extremely tree-shakable, meaning you only include what you use. You can think of it a bit like [FFmpeg](https://ffmpeg.org/), but built from the ground up for the web. + +[Documentation](https://mediabunny.dev) | [Examples](https://mediabunny.dev/examples) | [Sponsoring](#sponsoring) | [License](#license) + +### Gold sponsors + +
+ + Gling AI + +      + + Diffusion Studio + +
+ +[Get featured](https://github.com/sponsors/Vanilagy) + +## Features + +Core features include: + +- **Wide format support**: Read and write MP4, WebM, WAVE, MP3, Ogg, and more +- **Built-in encoding & decoding**: Supports 25+ video, audio, and subtitle codecs, hardware-accelerated using the WebCodecs API +- **High precision**: Fine-grained, microsecond-accurate reading and writing operations +- **Conversion API**: Easy-to-use API with features such as transmuxing, transcoding, resizing, rotation, resampling, trimming, and more +- **Streaming I/O**: Handle reading & writing files of any size with memory-efficient streaming +- **Tree-shakable**: Only bundle what you use (as small as 5 kB gzipped) +- **Zero dependencies**: Implemented in highly performant TypeScript +- **Cross-platform**: Works in browsers and Node.js + +[See full feature list](https://mediabunny.dev/guide/introduction#features) + +## Quick start + +### Installation + +```bash +npm install mediabunny +``` + +### Read file metadata + +```js +import { Input, ALL_FORMATS, BlobSource } from 'mediabunny'; + +const input = new Input({ + source: new BlobSource(file), // Reading from disk + formats: ALL_FORMATS, +}); + +const duration = await input.computeDuration(); // in seconds +const videoTrack = await input.getPrimaryVideoTrack(); +const audioTrack = await input.getPrimaryAudioTrack(); +const { displayWidth, displayHeight, rotation } = videoTrack; +const { sampleRate, numberOfChannels } = audioTrack; +``` + +### Create new media files + +```js +import { Output, Mp4OutputFormat, BufferTarget, CanvasSource, QUALITY_HIGH } from 'mediabunny'; + +const output = new Output({ + format: new Mp4OutputFormat(), + target: new BufferTarget(), // Writing to memory +}); + +// Add a video track backed by a canvas element +const videoSource = new CanvasSource(canvas, { + codec: 'avc', + bitrate: QUALITY_HIGH +}); +output.addVideoTrack(videoSource); + +await output.start(); +// Add frames... +await output.finalize(); + +const buffer = output.target.buffer; // Final MP4 file +``` + +### Convert files + +```js +import { Input, Output, Conversion, ALL_FORMATS, BlobSource, WebMOutputFormat } from 'mediabunny'; + +const input = new Input({ + source: new BlobSource(file), + formats: ALL_FORMATS, +}); + +const output = new Output({ + format: new WebMOutputFormat(), // Convert to WebM + target: new BufferTarget(), +}); + +const conversion = await Conversion.init({ input, output }); +await conversion.execute(); +``` + +[See more code snippets](https://mediabunny.dev/guide/quick-start) + +## Documentation + +Visit the [Docs](https://mediabunny.dev/guide/introduction) for comprehensive guides, examples and API documentation. + +## Sponsoring + +[See all sponsors](https://mediabunny.dev/#sponsors) + +Mediabunny is an open-source project released under the MPL-2.0 and is therefore free to use for any purpose, including closed-source commercial use. A permissive license is essential for a foundational library like this to truly thrive. That said, this project requires an immense amount of work and care to maintain and expand. This is made possible by the generous financial backing of the sponsors of this project. + +If you have derived considerable value from this project, please consider [sponsoring it](https://github.com/sponsors/Vanilagy) or providing a one-time donation. Thank you! 🩷 + +## License + +This project is licensed under the [Mozilla Public License 2.0](https://choosealicense.com/licenses/mpl-2.0/). This is a very permissive weak copyleft license, not much different from the MIT License, allowing you to: +- Use Mediabunny for any purpose, commercial or non-commercial, without royalties +- Use Mediabunny in open- and closed-source projects +- Freely distribute projects built with Mediabunny +- Inspect and modify Mediabunny's source code + +However, you have the following obligation: +- If you modify Mediabunny's licensed source code (e.g. in a fork) and then distribute it, you must publicly publish your modifications under the Mozilla Public License 2.0. + +This ensures that library usage remains permissive for everybody, while any improvements to Mediabunny remain in the open, benefiting everyone. + +You are not allowed to: +- Remove the license and copyright headers from any Mediabunny source file +- Claim the "Mediabunny" trademark + +And finally, Mediabunny - like any other library - comes with no warranty of any kind and is not liable for any direct or indirect damages. + +> This is not legal advice. Refer to the full text of the [Mozilla Public License 2.0](https://choosealicense.com/licenses/mpl-2.0/) for the binding license agreement. + +## Implementation & development + +Mediabunny is implemented from scratch in pure TypeScript with zero dependencies. At its core, the library is a collection of multiplexers and demultiplexers (one for every container format), which are then connected together via abstractions around the WebCodecs API. The logic is heavily pipelined and lazy, keeping performance high and memory usage low. If this stuff interests you, refer to the [Technical overview](https://mediabunny.dev/guide/introduction#technical-overview) for more. + +For development, clone this repository and install it using a modern version of Node.js and npm. The build system uses TypeScript, esbuild, API Extractor, Vite, and VitePress. + +```bash +npm install # Install dependencies +npm run watch # Development build with watch mode + +npm run build # Production build with type definitions + +npm run check # Type checking +npm run lint # ESLint + +npm run docs:dev # Start docs development server +npm run dev # Start examples development server + +npm run docs:build # Build docs and examples +``` \ No newline at end of file diff --git a/docs/guide/introduction.md b/docs/guide/introduction.md index 930600e..7aa8b37 100644 --- a/docs/guide/introduction.md +++ b/docs/guide/introduction.md @@ -1,6 +1,6 @@ # Introduction -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 kind of like [FFmpeg](https://ffmpeg.org/), but built for the web's needs. +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 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 a bit like [FFmpeg](https://ffmpeg.org/), but built for the web's needs. ## Features @@ -12,7 +12,7 @@ Here's a long list of stuff this library does: - 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) +- Read & write support for many container formats (.mp4, .mov, .webm, .mkv, .mp3, .wav, .ogg), including variations such as MP4 with Fast Start, fragmented MP4, or streamable Matroska - Support for 25 different codecs - Lazy, optimized, on-demand file reading - Input and output streaming, arbitrary file size support