Merge branch 'main' into fork-branch

docs/guide/converting-media-files.md

@@ -286,6 +286,44 @@ In this case, the output will be 15 seconds long.
 
 If only `start` is set, the clip will run until the end of the input file. If only `end` is set, the clip will start at the beginning of the input file.
 
+## Metadata tags
+
+By default, any [descriptive metadata tags](../api/MetadataTags.md) of the input will be copied to the output. If you want to further control the metadata tags written to the output, you can use the `tags` options:
+
+```ts
+// Set your own metadata:
+const conversion = await Conversion.init({
+	// ...
+	tags: () => ({
+		title: 're:Turning',
+		artist: 'Alexander Panos',
+	}),
+	// ...
+});
+
+// Or, augment the input's metadata:
+const conversion = await Conversion.init({
+	// ...
+	tags: inputTags => ({
+		...inputTags, // Keep the existing metadata
+		images: [{ // And add cover art
+			data: new Uint8Array(...),
+			mimeType: 'image/jpeg',
+			kind: 'coverFront',
+		}],
+		comment: undefined, // And remove any comments
+	}),
+	// ...
+});
+
+// Or, remove all metadata
+const conversion = await Conversion.init({
+	// ...
+	tags: () => ({}),
+	// ...
+});
+```
+
 ## Discarded tracks
 
 If an input track is excluded from the output file, it is considered *discarded*. The list of discarded tracks can be accessed after initializing a `Conversion`:

docs/guide/reading-media-files.md

@@ -60,6 +60,12 @@ await input.computeDuration(); // => 1905.4615
 ```
 More specifically, the duration is defined as the maximum end timestamp across all tracks.
 
+Mediabunny also lets you read descriptive metadata tags from media files, such as title, artist, or cover art:
+```ts
+await input.getMetadataTags(); // => MetadataTags
+```
+For more info, see [`MetadataTags`](../api/MetadataTags).
+
 ## Reading track metadata
 
 You can extract the list of all media tracks in the file like so:

docs/guide/writing-media-files.md

@@ -106,6 +106,25 @@ output.addAudioTrack(audioSource);
 Adding tracks to an `Output` will throw if the track is not compatible with the output format. Be sure to respect the [properties](./output-formats#format-properties) of the output format when adding tracks.
 :::
 
+## Setting metadata tags
+
+Mediabunny lets you write additional descriptive metadata tags to an output file, such as title, artist, or cover art:
+
+```ts
+output.setMetadataTags({
+	title: 'Big Buck Bunny',
+	artist: 'Blender Foundation',
+	date: new Date('2008-05-20'),
+	images: [{
+		data: new Uint8Array([...]),
+		mimeType: 'image/jpeg',
+		kind: 'coverFront',
+	}],
+});
+```
+
+For more info on which tags you can write, see [`MetadataTags`](../api/MetadataTags).
+
 ## Starting an output
 
 After all tracks have been added to the `Output`, you need to *start* it. Starting an output spins up the writing process, allowing you to now start sending media data to the output file. It also prevents you from adding any new tracks to it.