Foobar2000:Components/WebView (foo uie webview): Difference between revisions
m (use) |
(Initial version of the documentation) |
||
Line 8: | Line 8: | ||
| released = | | released = | ||
| released_ref = | | released_ref = | ||
| stable_release = 0.1. | | stable_release = 0.1.6.0 | ||
| stable_release_date = {{start date and age|2024|07| | | stable_release_date = {{start date and age|2024|07|09}} | ||
| preview_release = | | preview_release = 0.1.6.3-alpha3 | ||
| preview_release_date = | | preview_release_date = {{start date and age|2024|07|12}} | ||
| foobar2000_architecture = x86 32-bit, x86 64-bit | | foobar2000_architecture = x86 32-bit, x86 64-bit | ||
| foobar2000_minimum = 2.0 | | foobar2000_minimum = 2.0 | ||
Line 23: | Line 23: | ||
It takes an HTML file that receives playback notifications from foobar2000. The panel can react to those notifications and adjust its output using JavaScript code. | It takes an HTML file that receives playback notifications from foobar2000. The panel can react to those notifications and adjust its output using JavaScript code. | ||
The component supports multiple instances. Each instance can have its own settings and will use its own browser profile. | |||
==Setup== | |||
When you add a WebView panel to the foobar2000 user interface the following things happen: | |||
* The component tries to enable a supported WebView2 control. If no compatible WebView can be found the component will fail gracefully and report the error in the foobar2000 console. | |||
* A subdirectory called '''foo_uie_webview''' gets created in your foobar2000 profile directory. It will contain various state information used by WebView2. | |||
* The component looks by default for the HTML file '''foo_uie_webview\Template.html''' in your foobar2000 profile directory. The location of the template can be changed in the preferences page of the component. A copy of the default template will be created in that location if the file does not exist when the component starts. The example template provides working example code for all the component features. | |||
* A '''WebView''' preferences page is added to Preferences dialog in the '''Display''' category. | |||
<blockquote> | |||
The WebView2 control fills the complete client area of the panel and captures all mouse and keyboard events. The context menu will contain a '''WebView''' item to access the preferences of an instance. During '''Layout Edit''' mode the control will be hidden and only the '''WebView''' text will be shown. | |||
</blockquote> | |||
==Template== | |||
Basically anything you can do with HTML and JavaScript in WebView2 you can do with this panel. | |||
===Events=== | |||
Your JavaScript code can react to the following events raised by the component: | |||
<code>function OnPlaybackStarting(command, paused) {}</code> | |||
Called when playback is being initialized. | |||
''command'': The name of the command that started playback. | |||
''paused'': True if the playback was started paused. | |||
<code>function OnPlaybackNewTrack() {}</code> | |||
Called when playback advances to a new track. | |||
<code>function OnPlaybackStop(reason) {}</code> | |||
Called when playback stops. | |||
''reason'': The reason why playback got stopped ("User" / "EOF" / "Starting another" / "Shutting down") | |||
<code>function OnPlaybackSeek(time) {}</code> | |||
Called when the user seeks to a specific ''time'' (in seconds). | |||
<code>function OnPlaybackPause(paused) {}</code> | |||
Called when playback pauses or resumes. | |||
''paused'': True if the playback was started paused. | |||
<code>function OnPlaybackEdited() {}</code> | |||
Called when the currently played file gets edited. | |||
<code>function OnPlaybackDynamicInfo() {}</code> | |||
Called when dynamic info (VBR bitrate etc...) changes. | |||
<code>function OnPlaybackDynamicTrackInfo() {}</code> | |||
Called when the per-track dynamic info (stream track titles etc...) change. Happens less often than OnPlaybackDynamicInfo(). | |||
<code>function OnPlaybackTime(time) {}</code> | |||
Called, every second, for time display. | |||
<code>function OnVolumeChange(newValue) {}</code> | |||
Called when the user changes the volume. | |||
<code>function OnPlaylistFocusedItemChanged() {}</code> | |||
Called when the focused playlist item changes. | |||
===Shared Buffer=== | |||
A special feature of the component is the shared buffer between the component and the browser control. It will contain a copy of the foobar2000 visualization stream data allowing you to create visualizations in JavaScript. | |||
<code>function OnSharedBufferReceived(e) {}</code> | |||
This event gets raised when a new shared buffer is available to the JavaScript code. The following JavaScript code fragment get the samples as an ArrayBuffer and converts them to an array of 64-bit double values. | |||
<code>SharedBuffer = e.getBuffer(); // as an ArrayBuffer | |||
Samples = new Float64Array(SharedBuffer);</code> | |||
The '''e.additionalData''' property will specify the format of the buffer. | |||
* e.additionalData.SampleCount: The number of samples (for all channels) in the buffer | |||
* e.additionalData.SampleRate: The sample rate in Hz | |||
* e.additionalData.ChannelCount: The number of channels in the sample data. | |||
* e.additionalData.ChannelConfig: The channel configuration of the sample data. Take a look at the <code>function GetChannelConfigurationText(channelConfig)</code> function in the example template included in the component archive to learn how to interpret the '''ChannelConfig''' property value. | |||
==Host object== | |||
The component makes a special host object called '''chrome.webview.hostObjects.sync.foo_uie_webview''' available to JavaScript. The object provides the following methods and properties: | |||
===Properties=== | |||
* ComponentVersion and ComponentVersionText: The version of this component as packed integer and as text. | |||
* IsPlaying: Gets whether playback is active. | |||
* IsPaused: Gets whether playback is active and in paused state. | |||
* StopAfterCurrent: Gets or sets the stop-after-current-track option state. | |||
* Length: Gets the length of the currently playing item, in seconds. | |||
* Position: Gets the playback position within the currently playing item, in seconds. | |||
* CanSeek: Gets whether currently playing track is seekable. If it's not, Seek/SeekDelta calls will be ignored. | |||
* Volume: Gets or sets the playback volume in dBFS. Use 0 for full volume. | |||
* IsMuted: Gets whether playback is muted. | |||
===Methods=== | |||
* GetFormattedText(titleFormattingString): Interprets the [https://wiki.hydrogenaud.io/index.php?title=Foobar2000:Title_Formatting_Reference foobar2000 title formatting] string and returns the result. | |||
* Print(text): Prints text from JavaScript on the foobar2000 console. | |||
* Stop(): Stops playback. | |||
* Play(paused): Starts playback, paused or unpaused. If playback is already active, existing process is stopped first. | |||
* Pause(paused): Pauses or resumes playback. | |||
* Previous(): Plays the previous track from the current playlist according to the current playback order. | |||
* Next(): Plays the next track from the current playlist according to the current playback order. | |||
* Random(): Plays a random track from the current playlist (aka Shuffle). | |||
* TogglePause(): Toggles the pause status. | |||
* ToggleMute(): Toggles playback mute state. | |||
* ToggleStopAfterCurrent(): Toggles the stop-after-current mode. | |||
* VolumeUp(): Increases the volume with one step. | |||
* VolumeDown(): Decreases the volume with one step. | |||
* Seek(time): Seeks in the currently playing track to the specified time, in seconds. | |||
* SeekDelta(delta): Seeks in the currently playing track forward or backwards by the specified delta time, in seconds. | |||
* GetArtwork(artworktype): Returns the specified artwork as a data URI, either the file path of external artwork or the base64 encoded image data of embedded artwork. Artwork type can be: "front", "back", "disc", "icon" or "artist". | |||
==Preferences== | |||
The following settings can be changed on the preferences page. | |||
* Name: The name of the component | |||
* User data folder path: The root of the WebView2 user data folder. By default it gets created in your foobar2000 profile directory. When you change the location the old directory will '''not''' be moved or deleted automatically. | |||
* Template file path: The fully-qualified path of the HTML file to be used. The '''Edit''' button only works when an HTML editor is associated the the HTML file type and the Edit verb in Explorer. | |||
* Window size: The size of the window (in samples or seconds) to capture the foobar2000 visualization stream. | |||
* Reaction alignment: A parameter that allows you to tweak the alignment of the sample window. Positive values start the window behind the playback position; negative values start the window ahead of the playback position. | |||
* Clear browsing data on startup: The browser data cache will be cleared each time the instance starts. | |||
* In Private mode: The WebView2 control of the instance runs in '''In Private''' mode. |
Revision as of 15:54, 12 July 2024
WebView | |
---|---|
File:WebView.png | |
Developer(s) | ![]() |
Repository | GitHub |
Release information | |
Stable release | 0.1.6.0 (July 9, 2024; 0 years ago) |
Preview release | 0.1.6.3-alpha3 (July 12, 2024; 0 years ago) |
foobar2000 compatibility | |
Architecture | x86 32-bit, x86 64-bit |
Minimum version | 2.0 |
UI module(s) | Default UI, Columns UI |
Additional information | |
Use | UI |
License | MIT License |
View all components |
foo_uie_webview is a foobar2000 component that exposes the Microsoft WebView2 control as UI panel.
It takes an HTML file that receives playback notifications from foobar2000. The panel can react to those notifications and adjust its output using JavaScript code.
The component supports multiple instances. Each instance can have its own settings and will use its own browser profile.
Setup
When you add a WebView panel to the foobar2000 user interface the following things happen:
- The component tries to enable a supported WebView2 control. If no compatible WebView can be found the component will fail gracefully and report the error in the foobar2000 console.
- A subdirectory called foo_uie_webview gets created in your foobar2000 profile directory. It will contain various state information used by WebView2.
- The component looks by default for the HTML file foo_uie_webview\Template.html in your foobar2000 profile directory. The location of the template can be changed in the preferences page of the component. A copy of the default template will be created in that location if the file does not exist when the component starts. The example template provides working example code for all the component features.
- A WebView preferences page is added to Preferences dialog in the Display category.
The WebView2 control fills the complete client area of the panel and captures all mouse and keyboard events. The context menu will contain a WebView item to access the preferences of an instance. During Layout Edit mode the control will be hidden and only the WebView text will be shown.
Template
Basically anything you can do with HTML and JavaScript in WebView2 you can do with this panel.
Events
Your JavaScript code can react to the following events raised by the component:
function OnPlaybackStarting(command, paused) {}
Called when playback is being initialized.
command: The name of the command that started playback. paused: True if the playback was started paused.
function OnPlaybackNewTrack() {}
Called when playback advances to a new track.
function OnPlaybackStop(reason) {}
Called when playback stops.
reason: The reason why playback got stopped ("User" / "EOF" / "Starting another" / "Shutting down")
function OnPlaybackSeek(time) {}
Called when the user seeks to a specific time (in seconds).
function OnPlaybackPause(paused) {}
Called when playback pauses or resumes.
paused: True if the playback was started paused.
function OnPlaybackEdited() {}
Called when the currently played file gets edited.
function OnPlaybackDynamicInfo() {}
Called when dynamic info (VBR bitrate etc...) changes.
function OnPlaybackDynamicTrackInfo() {}
Called when the per-track dynamic info (stream track titles etc...) change. Happens less often than OnPlaybackDynamicInfo().
function OnPlaybackTime(time) {}
Called, every second, for time display.
function OnVolumeChange(newValue) {}
Called when the user changes the volume.
function OnPlaylistFocusedItemChanged() {}
Called when the focused playlist item changes.
A special feature of the component is the shared buffer between the component and the browser control. It will contain a copy of the foobar2000 visualization stream data allowing you to create visualizations in JavaScript.
function OnSharedBufferReceived(e) {}
This event gets raised when a new shared buffer is available to the JavaScript code. The following JavaScript code fragment get the samples as an ArrayBuffer and converts them to an array of 64-bit double values.
SharedBuffer = e.getBuffer(); // as an ArrayBuffer
Samples = new Float64Array(SharedBuffer);
The e.additionalData property will specify the format of the buffer.
- e.additionalData.SampleCount: The number of samples (for all channels) in the buffer
- e.additionalData.SampleRate: The sample rate in Hz
- e.additionalData.ChannelCount: The number of channels in the sample data.
- e.additionalData.ChannelConfig: The channel configuration of the sample data. Take a look at the
function GetChannelConfigurationText(channelConfig)
function in the example template included in the component archive to learn how to interpret the ChannelConfig property value.
Host object
The component makes a special host object called chrome.webview.hostObjects.sync.foo_uie_webview available to JavaScript. The object provides the following methods and properties:
Properties
- ComponentVersion and ComponentVersionText: The version of this component as packed integer and as text.
- IsPlaying: Gets whether playback is active.
- IsPaused: Gets whether playback is active and in paused state.
- StopAfterCurrent: Gets or sets the stop-after-current-track option state.
- Length: Gets the length of the currently playing item, in seconds.
- Position: Gets the playback position within the currently playing item, in seconds.
- CanSeek: Gets whether currently playing track is seekable. If it's not, Seek/SeekDelta calls will be ignored.
- Volume: Gets or sets the playback volume in dBFS. Use 0 for full volume.
- IsMuted: Gets whether playback is muted.
Methods
- GetFormattedText(titleFormattingString): Interprets the foobar2000 title formatting string and returns the result.
- Print(text): Prints text from JavaScript on the foobar2000 console.
- Stop(): Stops playback.
- Play(paused): Starts playback, paused or unpaused. If playback is already active, existing process is stopped first.
- Pause(paused): Pauses or resumes playback.
- Previous(): Plays the previous track from the current playlist according to the current playback order.
- Next(): Plays the next track from the current playlist according to the current playback order.
- Random(): Plays a random track from the current playlist (aka Shuffle).
- TogglePause(): Toggles the pause status.
- ToggleMute(): Toggles playback mute state.
- ToggleStopAfterCurrent(): Toggles the stop-after-current mode.
- VolumeUp(): Increases the volume with one step.
- VolumeDown(): Decreases the volume with one step.
- Seek(time): Seeks in the currently playing track to the specified time, in seconds.
- SeekDelta(delta): Seeks in the currently playing track forward or backwards by the specified delta time, in seconds.
- GetArtwork(artworktype): Returns the specified artwork as a data URI, either the file path of external artwork or the base64 encoded image data of embedded artwork. Artwork type can be: "front", "back", "disc", "icon" or "artist".
Preferences
The following settings can be changed on the preferences page.
- Name: The name of the component
- User data folder path: The root of the WebView2 user data folder. By default it gets created in your foobar2000 profile directory. When you change the location the old directory will not be moved or deleted automatically.
- Template file path: The fully-qualified path of the HTML file to be used. The Edit button only works when an HTML editor is associated the the HTML file type and the Edit verb in Explorer.
- Window size: The size of the window (in samples or seconds) to capture the foobar2000 visualization stream.
- Reaction alignment: A parameter that allows you to tweak the alignment of the sample window. Positive values start the window behind the playback position; negative values start the window ahead of the playback position.
- Clear browsing data on startup: The browser data cache will be cleared each time the instance starts.
- In Private mode: The WebView2 control of the instance runs in In Private mode.