Set up examples folder structure

.gitignore

@@ -1,5 +1,6 @@
 /node_modules
 /build
 /dist
+/dist-docs
 .DS_Store
 /docs/.vitepress/cache

docs/.vitepress/config.mts

@@ -63,4 +63,5 @@ export default withMermaid({
 			md.use(footnote);
 		},
 	},
+	outDir: '../dist-docs',
 });

docs/guide/media-sources.md

@@ -25,7 +25,7 @@ Closing sources manually is _technically_ not required and will happen automatic
 
 ### Backpressure
 
-Media sources are the means by which backpressure is propagated from the output pipeline into your application logic. The `Output` may want to apply backpressure if the encoders or the [StreamTarget](./writing-overview/#streamtarget)'s writable can't keep up.
+Media sources are the means by which backpressure is propagated from the output pipeline into your application logic. The `Output` may want to apply backpressure if the encoders or the [StreamTarget](./writing-overview#streamtarget)'s writable can't keep up.
 
 Backpressure is communicated by media sources via promises. All media sources with an `add` method return a promise:
 ```ts
@@ -67,7 +67,7 @@ type VideoEncodingConfig = {
 	) => unknown;
 };
 ```
-- `codec`: The [video codec](./supported-formats-and-codecs/#video-codecs) used for encoding.
+- `codec`: The [video codec](./supported-formats-and-codecs#video-codecs) used for encoding.
 - `bitrate`: The target number of bits per second. Alternatively, this can be a [subjective quality](#subjective-qualities).
 - `latencyMode`: The latency mode as specified by the WebCodecs API. Media stream-driven video sources will automatically use the `realtime` setting.
 - `keyFrameInterval`: The maximum interval in seconds between two adjacent key frames. Defaults to 5 seconds. More frequent key frames improve seeking behavior but increase file size. When using multiple video tracks, this value should be set to the same value for all tracks.
@@ -97,7 +97,7 @@ type AudioEncodingConfig = {
 	) => unknown;
 };
 ```
-- `codec`: The [audio codec](./supported-formats-and-codecs/#audio-codecs) used for encoding. Can be omitted for uncompressed PCM codecs.
+- `codec`: The [audio codec](./supported-formats-and-codecs#audio-codecs) used for encoding. Can be omitted for uncompressed PCM codecs.
 - `bitrate`: The target number of bits per second. Alternatively, this can be a [subjective quality](#subjective-qualities).
 - `fullCodecString`: Allows you to optionally specify the full codec string used by the audio encoder, as specified in the [WebCodecs Codec Registry](https://www.w3.org/TR/webcodecs-codec-registry/). For example, you may set it to `'mp4a.40.2'` when using AAC. Keep in mind that the codec string must still match the codec specified in `codec`. If you don't set this field, a codec string will be generated automatically.
 - `onEncodedPacket`: Called for each successfully encoded packet. Useful for determining encoding progress.	

docs/guide/reading-overview.md

@@ -407,7 +407,13 @@ fileInput.addEventListener('change', (event) => {
 });
 ```
 
-### `UrlSource`
+### `UrlSource` <Badge type="warning" text="beta" />
+
+::: warning
+This is a **beta** feature. `UrlSource` tends to make tons of requests and is potentially slow. This is something that will be fixed in the near future.
+
+It still works, but keep in mind it's going to be much higher-latency than reading directly from disk or from memory.
+:::
 
 This source fetches data from a URL. This is useful for reading files over the network.
 ```ts
@@ -417,9 +423,7 @@ const source = new UrlSource('https://example.com/bigbuckbunny.mp4');
 ```
 
 ::: warning
-Keep in mind that reading data over the network is typically much higher-latency than reading directly from disk or from memory.
-
-Also, if you're using this source in the browser and the URL is on a different origin, make sure [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS) is properly configured.
+If you're using this source in the browser and the URL is on a different origin, make sure [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS) is properly configured.
 :::
 
 `UrlSource` accepts a few options as its second parameter:

docs/guide/writing-overview.md

@@ -38,7 +38,7 @@ output.addAudioTrack(audioSource);
 output.addSubtitleTrack(subtitleSource);
 ```
 
-For each track you want to add, you'll need to create a unique [media source](./media-source) for it. You'll be able to add media data to the output via these media sources. A media source can only ever be used for one output track.
+For each track you want to add, you'll need to create a unique [media source](./media-sources) for it. You'll be able to add media data to the output via these media sources. A media source can only ever be used for one output track.
 
 Optionally, you can specify additional track metadata when adding tracks:
 ```ts
@@ -115,7 +115,7 @@ await output.start(); // Resolves once the output is ready to receive media data
 
 ## Adding media data
 
-After starting an `Output`, you can use the media sources you used to add tracks to pipe media data to the output file. The API for this is different for each [media source](./media-source), but it typically looks something like this:
+After starting an `Output`, you can use the media sources you used to add tracks to pipe media data to the output file. The API for this is different for each [media source](./media-sources), but it typically looks something like this:
 ```ts
 mediaSource.add(...);
 ```

docs/index.md

@@ -24,15 +24,24 @@ features:
 ---
 
 things the guide needs to cover:
-- writing files
-	- output usage
-	- all output formats
-	- all media sources
-- reading files
-	- input usage
-	- all input formats
-	- all media sinks
-- utility functions
-- supported containers / codecs
-- samples & packets
-- conversion
+- writing files ✅
+	- output usage ✅
+	- all output formats ✅
+	- all media sources ✅
+- reading files ✅
+	- input usage ✅
+	- all input formats ✅
+	- all media sinks ✅
+- utility functions ✅
+- supported containers / codecs ✅
+- samples & packets ✅
+- conversion
+
+Examples:
+- Extracting media file metadata
+- Rendering thumbnails for a video / extracting a wave form?
+- Media player
+- Conversion demo: File compressor
+- Procedurally generated video (faster than real time)
+- Video generated from live sources
+- Live streaming demo?

examples/example-a/index.html

@@ -0,0 +1,3 @@
+<p>hello!</p>
+
+<script type="module" src="./script.ts"></script>

examples/example-a/script.ts

@@ -0,0 +1,3 @@
+import * as Mediakit from 'mediakit';
+
+console.log(Mediakit);

examples/example-b/index.html

@@ -0,0 +1,3 @@
+<p>goodbye!</p>
+
+<script type="module" src="./script.ts"></script>

examples/example-b/script.ts

@@ -0,0 +1,3 @@
+import * as Mediakit from 'mediakit';
+
+console.log('kekw', Mediakit);

package.json

@@ -2,6 +2,7 @@
   "name": "metamuxer",
   "version": "0.1.0",
   "description": "TODO",
+  "type": "module",
   "main": "./dist/metamuxer.js",
   "module": "./dist/metamuxer.mjs",
   "types": "./dist/metamuxer.d.ts",
@@ -17,15 +18,17 @@
     "dist"
   ],
   "scripts": {
-    "build": "node build.mjs && tsc -p src && api-extractor run && npm run check-docblocks && ts-node scripts/append-namespace.ts",
-    "build-local": "node build.mjs && tsc -p src && api-extractor run --local --verbose && npm run check-docblocks && ts-node scripts/append-namespace.ts",
+    "build": "node build.mjs && tsc -p src && api-extractor run && npm run check-docblocks && tsx scripts/append-namespace.ts",
+    "build-local": "node build.mjs && tsc -p src && api-extractor run --local --verbose && npm run check-docblocks && tsx scripts/append-namespace.ts",
     "watch": "node build.mjs --watch",
     "lint": "eslint .",
     "check": "tsc -p src --noEmit && tsc -p scripts --noEmit",
-    "check-docblocks": "ts-node scripts/check-docblocks dist/metamuxer.d.ts",
+    "check-docblocks": "tsx scripts/check-docblocks.ts dist/metamuxer.d.ts",
     "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs"
+    "docs:build": "vitepress build docs && npm run examples:build",
+    "docs:preview": "vitepress preview docs",
+    "dev": "vite",
+    "examples:build": "vite build"
   },
   "author": "",
   "license": "MIT",
@@ -44,9 +47,10 @@
     "markdown-it-footnote": "^4.0.0",
     "markdown-it-mathjax3": "^4.3.2",
     "mermaid": "^11.6.0",
-    "ts-node": "^10.9.2",
+    "tsx": "^4.19.4",
     "typescript": "^5.8.2",
     "typescript-eslint": "^8.26.1",
+    "vite": "^6.3.5",
     "vitepress": "^1.6.3",
     "vitepress-plugin-mermaid": "^2.0.17"
   }

src/source.ts

@@ -152,7 +152,7 @@ export type UrlSourceOptions = {
 /**
  * A source backed by a URL. This is useful for reading data from the network. Be careful using this source however,
  * as it typically comes with increased latency.
- * @public
+ * @beta
  */
 export class UrlSource extends Source {
 	/** @internal */

tsconfig.json

@@ -9,5 +9,8 @@
 		"skipLibCheck": true,
 		"allowJs": true,
 		"noEmit": true
-	}
+	},
+	"references": [
+		{ "path": "./tsconfig.vite.json" }
+	]
 }

tsconfig.vite.json

@@ -0,0 +1,16 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"moduleResolution": "nodenext",
+		"module": "NodeNext",
+		"composite": true,
+		"noEmit": false,
+		"paths": {
+			"mediakit": ["./dist/metamuxer.d.ts"],
+		},
+	},
+	"include": [
+		"./vite.config.ts",
+		"./examples/**/*.ts",
+	]
+}

vite.config.ts

@@ -0,0 +1,33 @@
+import { defineConfig } from 'vite';
+import path from 'path';
+import fs from 'fs';
+
+const examplesDir = path.resolve(__dirname, './examples');
+
+const exampleFolders = fs
+	.readdirSync(examplesDir, { withFileTypes: true })
+	.filter(dirent => dirent.isDirectory())
+	.map(dirent => dirent.name);
+
+const rollupInput = Object.fromEntries(
+	exampleFolders.map(folderName => [
+		folderName,
+		path.resolve(examplesDir, folderName, 'index.html'),
+	]),
+);
+
+export default defineConfig({
+	resolve: {
+		alias: {
+			mediakit: path.resolve(__dirname, './dist/metamuxer.mjs'),
+		},
+	},
+	build: {
+		outDir: 'dist-docs', // Build them directly into the docs build folder
+		emptyOutDir: false,
+		rollupOptions: {
+			input: rollupInput,
+		},
+		minify: false,
+	},
+});