Skip to content

Commit 72c62d0

Browse files
Danielku15Danielku15
authored
docs: Audio Export Docs (#138)
1 parent 10e8681 commit 72c62d0

File tree

10 files changed

+404
-3
lines changed

10 files changed

+404
-3
lines changed

‎docs/guides/audio-export.mdx‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
title: Audio Export
3+
since: 1.6.0
4+
---
5+
import { SinceBadge } from '@site/src/components/SinceBadge';
6+
7+
<SinceBadge since="1.6.0" />
8+
9+
This guides shows how to use alphaTab to generate raw audio samples for exporting purposes. The export feature serves following use cases:
10+
11+
1. Allow users to download an audio file of the song. <br /><br />
12+
If the audio is passed additionally to an audio codec like MP3 or OGG Vorbis, users can save the audio of the music sheet to disk.
13+
This is a quite common feature offered to users.
14+
15+
2. Use the raw audio for synchronization with external systems. <br /><br />
16+
You app might have its own mechanisms to provide media playback. Your app might have additional custom backing tracks or you want to splitup
17+
the individual audio tracks to play on separate output devices. By pre-computing the audio samples from the synthesizer you can
18+
build an external system which combines the alphaTab audio with any custom components.
19+
20+
The external system can then be combined this with the [Audio & Video Sync](/docs/guides/audio-video-sync) feature to still have an interactive music sheet that shows correctly what's being played.
21+
22+
23+
> [!NOTE]
24+
> The audio export can be used regardless of the current mode the alphaTab player is in. This allows exporting audio even if an external audio backing track or video is used.
25+
> Just be sure to pass in the required soundfont in this case. If a synthesizer is already active, it can reuse the already loaded soundfont.
26+
27+
## How to use this?
28+
29+
The audio exporter follows an asynchronous pull pattern:
30+
31+
* _async_ because the exporter uses `Promises` (`Task` for C#, `Deferred` for Kotlin) to provide a clean way of requesting audio data without fighting with callbacks or events.
32+
* _pull_ because you request the next chunk of audio to be generated and pull the audio into your consumer code.
33+
34+
To export the audio you follow tree main steps:
35+
36+
1. You start a new exporter with [`await api.exportAudio(...)`](/docs/reference/api/exportaudio.mdx).
37+
2. You call [`exporter.render(<milliseconds>)`](/docs/reference/types/synth/iaudioexporter/render.mdx) to produce a chunk of audio which you can then process further. (repeated until end is reached).
38+
3. You cleanup the exporter via [`exporter.destroy()`](/docs/reference/types/synth/iaudioexporter/destroy.mdx). The exporter also implements `Disposable` (`IDisposable` for C#, `AutoCloseable` for `Kotlin`) which allows easy cleanup via language features if supported.
39+
40+
> [!WARNING]
41+
> The raw audio samples for a whole song can consume quite a huge amount of memory: A calculation example:
42+
>
43+
> * 4 bytes per sample (32-bit float samples)
44+
> * 2 audio channels (left and right for stereo sound)
45+
> * 44100 samples per second
46+
>
47+
> A 1 minute song already needs ~21MB of memory (`60s * 4bytes * 2channels * 44100samples/s`), multiply accordingly.
48+
>
49+
> To keep the memory pressure low, you might send the chunks into a 3rd party library encoding the audio in a smaller format (e.g. MP3 or OGG Vorbis).
50+
51+
### Available options
52+
53+
The [`AudioExportOptions`](/docs/reference/types/synth/audioexportoptions/index.mdx) allow customizing various aspects of the audio exported:
54+
55+
* [`soundFonts`](/docs/reference/types/synth/audioexportoptions/soundfonts.mdx) can be used to customize the soundfonts used during export.
56+
* [`sampleRate`](/docs/reference/types/synth/audioexportoptions/samplerate.mdx) can be used to customize the sample rate of the exported audio.
57+
* [`useSyncPoints`](/docs/reference/types/synth/audioexportoptions/usesyncpoints.mdx) controls whether the sync points of the currently loaded song are appled during audio generation.
58+
* [`masterVolume`](/docs/reference/types/synth/audioexportoptions/mastervolume.mdx) controls the master volume of the generated audio.
59+
* [`metronomeVolume`](/docs/reference/types/synth/audioexportoptions/metronomevolume.mdx) controls the volume of the metronome ticks. (keep in mind that the use of `useSyncPoints` changes the audio duration, the metronome is aligned with the music notes, not with the synthesized audio)
60+
* [`playbackRange`](/docs/reference/types/synth/audioexportoptions/playbackrange.mdx) controls the audio range which is exported.
61+
* [`trackVolume`](/docs/reference/types/synth/audioexportoptions/trackvolume.mdx) controls the volume of every track (percentage-wise to the already configured absolute volume)
62+
* [`trackTranspositionPitches`](/docs/reference/types/synth/audioexportoptions/tracktranspositionpitches.mdx) controls an additional transposition pitch for the tracks.
63+
64+
## Example
65+
66+
This example exports the audio and creates a [WAV File](https://en.wikipedia.org/wiki/WAV) out of the samples. WAV files contain the raw samples, we just need
67+
to write the correct file header. In this demo we then create a Blob URL in the browser to set the WAV file as source of an `<audio />` tag to play it.
68+
69+
import { AudioExportSample } from '@site/src/components/AudioExportSample';
70+
71+
<AudioExportSample />

‎docs/guides/audio-video-sync.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
---
22
title: Audio & Video Sync
3+
since: 1.6.0
34
---
5+
import { SinceBadge } from '@site/src/components/SinceBadge';
6+
7+
<SinceBadge since="1.6.0" />
48

59
alphaTab can be synchronized with an external audio or video backing track. You can either use Guitar Pro 8 files with an audio track or synchronize alphaTab with an external media using the
610
[Media Sync Editor in the Playground](/docs/playground/playground.mdx).

‎docs/guides/media-sync-editor.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
---
22
title: Media Sync Editor
3+
since: 1.6.0
34
---
5+
import { SinceBadge } from '@site/src/components/SinceBadge';
6+
7+
<SinceBadge since="1.6.0" />
48

59
This guide is about the Media Sync Editor we provide as part of our [Playground](/docs/playground/playground.mdx).
610

‎docs/reference/api/exportaudio.mdx‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
title: exportAudio
3+
description: "Starts the audio export for the currently loaded song."
4+
sidebar_custom_props:
5+
kind: method
6+
category: Methods - Player
7+
since: 1.5.0
8+
---
9+
10+
import { ParameterTable, ParameterRow } from '@site/src/components/ParameterTable';
11+
import CodeBlock from '@theme/CodeBlock';
12+
import Tabs from "@theme/Tabs";
13+
import TabItem from "@theme/TabItem";
14+
import { CodeBadge } from '@site/src/components/CodeBadge';
15+
import { SinceBadge } from '@site/src/components/SinceBadge';
16+
import DynHeading from '@site/src/components/DynHeading';
17+
import Link from '@docusaurus/Link';
18+
19+
<SinceBadge since="1.5.0" />
20+
21+
### Description
22+
Starts the audio export for the currently loaded song. This will not export or use any backing track media but will always use the synthesizer to generate the output.
23+
This method works with any PlayerMode active but changing the mode during export can lead to unexpected side effects.
24+
25+
See [Audio Export](/docs/guides/audio-export) for further guidance how to use this feature.
26+
27+
<Tabs defaultValue="js" values={[{label: "JavaScript", value: "js"},{label: "C#", value: "cs"},{label:"Kotlin", value: "kt"}]}>
28+
<TabItem value="js">
29+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"exportAudio"}</span><span style={{"color":"#393A34"}}>{"("}</span><span style={{"color":"#36acaa"}}>{"options"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><Link style={{"color":"#36acaa"}} to={"/docs/reference/types/synth/audioexportoptions"}>{"AudioExportOptions"}</Link><span style={{"color":"#393A34"}}>{")"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><Link style={{"color":"#36acaa"}} to={"/docs/reference/types/synth/iaudioexporter"}>{"Promise"}</Link><span style={{"color":"#393A34"}}>{"<"}</span><Link style={{"color":"#36acaa"}} to={"/docs/reference/types/synth/iaudioexporter"}>{"IAudioExporter"}</Link><span style={{"color":"#393A34"}}>{">"}</span></code></pre></div></div>
30+
</TabItem>
31+
<TabItem value="cs">
32+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><Link style={{"color":"#36acaa"}} to={"https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.task-1"}>{"System.Threading.Task"}</Link><span style={{"color":"#393A34"}}>{"<"}</span><Link style={{"color":"#36acaa"}} to={"/docs/reference/types/synth/iaudioexporter"}>{"IAudioExporter"}</Link><span style={{"color":"#393A34"}}>{">"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"ExportAudio"}</span><span style={{"color":"#393A34"}}>{"("}</span><Link style={{"color":"#36acaa"}} to={"/docs/reference/types/synth/audioexportoptions"}>{"AudioExportOptions"}</Link><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"options"}</span><span style={{"color":"#393A34"}}>{")"}</span></code></pre></div></div>
33+
</TabItem>
34+
<TabItem value="kt">
35+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"suspend"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"fun"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"exportAudio"}</span><span style={{"color":"#393A34"}}>{"("}</span><span style={{"color":"#36acaa"}}>{"options"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><Link style={{"color":"#36acaa"}} to={"/docs/reference/types/synth/audioexportoptions"}>{"AudioExportOptions"}</Link><span style={{"color":"#393A34"}}>{")"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><Link style={{"color":"#36acaa"}} to={"/docs/reference/types/synth/iaudioexporter"}>{"IAudioExporter"}</Link></code></pre></div></div>
36+
</TabItem>
37+
</Tabs>
38+
39+
40+
<ParameterTable>
41+
<ParameterRow platform="all" name="options">
42+
The export options.
43+
</ParameterRow>
44+
</ParameterTable>
45+
46+
### Returns
47+
An exporter instance to export the audio in a streaming fashion.
48+

‎docs/reference/api/updatesyncpoints.mdx‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
title: updateSyncPoints
3+
description: "Triggers an update of the sync points for the current score after modification within the data model"
4+
sidebar_custom_props:
5+
kind: method
6+
category: Methods - Player
7+
since: 1.6.0
8+
---
9+
10+
import { ParameterTable, ParameterRow } from '@site/src/components/ParameterTable';
11+
import CodeBlock from '@theme/CodeBlock';
12+
import Tabs from "@theme/Tabs";
13+
import TabItem from "@theme/TabItem";
14+
import { CodeBadge } from '@site/src/components/CodeBadge';
15+
import { SinceBadge } from '@site/src/components/SinceBadge';
16+
import DynHeading from '@site/src/components/DynHeading';
17+
import Link from '@docusaurus/Link';
18+
19+
<SinceBadge since="1.6.0" />
20+
21+
### Description
22+
Triggers an update of the sync points for the current score after modification within the data model
23+
24+
<Tabs defaultValue="js" values={[{label: "JavaScript", value: "js"},{label: "C#", value: "cs"},{label:"Kotlin", value: "kt"}]}>
25+
<TabItem value="js">
26+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"updateSyncPoints"}</span><span style={{"color":"#393A34"}}>{"("}</span><span style={{"color":"#393A34"}}>{")"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"void"}</span></code></pre></div></div>
27+
</TabItem>
28+
<TabItem value="cs">
29+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#00009f"}}>{"void"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"UpdateSyncPoints"}</span><span style={{"color":"#393A34"}}>{"("}</span><span style={{"color":"#393A34"}}>{")"}</span></code></pre></div></div>
30+
</TabItem>
31+
<TabItem value="kt">
32+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"fun"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"updateSyncPoints"}</span><span style={{"color":"#393A34"}}>{"("}</span><span style={{"color":"#393A34"}}>{")"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"Unit"}</span></code></pre></div></div>
33+
</TabItem>
34+
</Tabs>
35+

‎docs/reference/settings/core/fontdirectory.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,5 +27,7 @@ where the Web Font files of [Bravura](https://github.com/steinbergmedia/bravura)
2727
them to be in a `font` subfolder beside the script file. If this is not the case, this setting must be used to configure the path.
2828
Alternatively also a global variable `ALPHATAB_FONT` can be set on the page before initializing alphaTab.
2929

30+
Use <code style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><Link style={{"color":"#36acaa"}} to={"/docs/reference/settings/core/smuflfontsources"}>{"smuflFontSources"}</Link></code> for more flexible font configuration.
31+
3032
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"fontDirectory"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"string"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"|"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#00009f"}}>{"null"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"\"${AlphaTabScriptFolder}/font/\""}</span><span style={{"color":"#393A34"}}>{";"}</span></code></pre></div></div>
3133

‎docs/reference/settings/core/smuflfontsources.mdx‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: core.smuflFontSources
3+
description: "Defines the URLs from which to load the SMuFL compliant font files."
4+
sidebar_custom_props:
5+
javaScriptOnly: true
6+
jsOnParent: true
7+
category: Core - JavaScript Specific
8+
since: 1.6.0
9+
---
10+
11+
import { ParameterTable, ParameterRow } from '@site/src/components/ParameterTable';
12+
import CodeBlock from '@theme/CodeBlock';
13+
import Tabs from "@theme/Tabs";
14+
import TabItem from "@theme/TabItem";
15+
import { CodeBadge } from '@site/src/components/CodeBadge';
16+
import { SinceBadge } from '@site/src/components/SinceBadge';
17+
import DynHeading from '@site/src/components/DynHeading';
18+
import Link from '@docusaurus/Link';
19+
20+
import { SettingsHeader } from '@site/src/components/SettingsHeader';
21+
22+
<SettingsHeader />
23+
24+
### Description
25+
Defines the URLs from which to load the SMuFL compliant font files. These sources will be used to load and register the webfonts on the page so
26+
they are available for rendering the music sheet. The sources can be set to any
27+
CSS compatible URL which can be passed into `url()`.
28+
See https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src#url
29+
30+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"smuflFontSources"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><Link style={{"color":"#36acaa"}} to={"/docs/reference/types/fontfileformat"}>{"Map"}</Link><span style={{"color":"#393A34"}}>{"<"}</span><Link style={{"color":"#36acaa"}} to={"/docs/reference/types/fontfileformat"}>{"FontFileFormat"}</Link><span style={{"color":"#393A34"}}>{","}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"string"}</span><span style={{"color":"#393A34"}}>{">"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"|"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#00009f"}}>{"null"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"Bravura files located at <code style={{\"color\":\"#393A34\",\"backgroundColor\":\"#f6f8fa\"}}><Link style={{\"color\":\"#36acaa\"}} to={\"/docs/reference/settings/core/fontdirectory\"}>{\"fontDirectory\"}</Link></code> ."}</span><span style={{"color":"#393A34"}}>{";"}</span></code></pre></div></div>
31+

0 commit comments

Comments
 (0)