Web Components
The web component build of Flipnote.js provides a set of custom HTML tags that can be used to easily embed a Flipnote player UI (<flipnote-player>
) or Flipnote image (<flipnote-image>
) in any webpage.
Installation
Installing the web component build is very similar to the usual installation steps listed on the Get Started page, except we import a different file that has the additional web component code included.
From a CDN (web)
<script src="https://cdn.jsdelivr.net/npm/flipnote.js@6/dist/flipnote.webcomponent.min.js"></script>
Self-host (web)
From NPM (web via a bundler)
// with the es6 import syntax:import flipnote from 'flipnote.js/webcomponent';// or with the older require() function:const flipnote = require('flipnote.js/webcomponent');
flipnote-player
The <flipnote-player>
element behaves almost exactly like the standard HTML5 <video>
element, except it can play any valid Flipnote Studio .ppm or .kwz animation file directly in the browser. It also provides a cute playback UI, inspired by my web-based Flipnote Player.
Here’s what it looks like:
Basic usage
After inserting the script into your page, all you need to do is put a <flipnote-player>
tag somewhere in your HTML, and give it a src
attribute pointing to the URL of a Flipnote Studio .ppm or .kwz file:
<flipnote-player src="./path/to/some/flipnote.kwz"></flipnote-player>
And… that’s it!
Attributes
src
The src
attribute tells the player what Flipnote it should load, and it should point to the URL of a Flipnote Studio .ppm or .kwz animation file. This attribute be changed at any time to load another Flipnote into the same player.
The player can also load Flipnotes from other kinds of sources, such as from JavaScript ArrayBuffer
or File
objects. For more information on this, check out the JavaScript API section.
controls
The controls
attribute can select between a couple of different UI control layouts.
Default:
<flipnote-player src="./path/to/some/flipnote.ppm"></flipnote-player>
compact
:
<flipnote-player controls="compact" src="./path/to/some/flipnote.ppm"></flipnote-player>
cropBorder
Set cropBorder="true"
to make the player remove the border around KWZ frames. If used with dsiLibrary
, this will also crop a Nintendo DSi Library KWZ to the dimensions of the original PPM it was converted from. This value can not be updated after a Flipnote is loaded.
dsiLibrary
Set dsiLibrary="true"
to enable special processing for KWZs from Nintendo DSi Library. This value can not be updated after a Flipnote is loaded.
bgmPredictor
Some DSi Library KWZs have very broken audio since Nintendo messed up the conversion from the PPM format. While flipnote.js has a built-in correction algorithm for this, very advanced users can instead provide your own ADPCM state values if they really want to. If dsiLibrary
is set to true
, the value of bgmPredictor
will provide the initial ADPCM predictor value when decoding the BGM track. This value can not be updated after a Flipnote is loaded.
bgmStepIndex
Like bgmPredictor
, the value of bgmStepIndex
will provide the initial ADPCM step index value when decoding the BGM track. This value can not be updated after a Flipnote is loaded.
sePredictors
Like bgmPredictor
, the value of sePredictors
will provide the initial ADPCM predictor values when decoding each sound effect track, as a comma-separated list in the order of SE1, SE2, SE3 then SE4 (e.g sePredictors="100,100,100,-100"
). This value can not be updated after a Flipnote is loaded.
seStepIndices
Like bgmStepIndex
, the value of seStepIndices
will provide the initial ADPCM step index values when decoding each sound effect track, as a comma-separated list in the order of SE1, SE2, SE3 then SE4 (e.g seStepIndices="40,40,40,39"
). This value can not be updated after a Flipnote is loaded.
Styling
Some CSS Variables can also be used to style various elements of the player UI. You can override any these variables to provide your own styles to the component via CSS, like so:
flipnote-player { --flipnote-player-font-family: 'Helvetica'; --flipnote-player-button-background: red;}
Available CSS variables
CSS variable | Default value | Purpose |
---|---|---|
--flipnote-player-font-family | sans-serif | Font to use for any player UI text |
--flipnote-player-canvas-background | #FFF | Canvas area background - this will only be visible if the Flipnote is a KWZ and uses a transparent background color |
--flipnote-player-controls-background | none | Background color for the controls area |
--flipnote-player-button-background | #FFD3A6 | Button background color |
--flipnote-player-button-color | #F36A2D | Button text color |
--flipnote-player-icon-color | #F36A2D | Color used by icons in the player UI |
--flipnote-player-slider-track | #FFD3A6 | Slider track color |
--flipnote-player-slider-level | #F36A2D | Slider level color |
--flipnote-player-slider-handle | #F36A2D | Slider handle outer color |
--flipnote-player-slider-handle-fill | white | Slider handle inner color |
--flipnote-player-focus-outline | 3px solid #FFD3A6 | Outline used when the player UI is focused |
Styling via Parts
If you need more styling options, every player element has a part
attribute that you can use to target specific parts of the player UI from CSS, like so:
flipnote-player::part(Controls) { background: red;}
It’s recommended to use browser developer tools to inspect the parts of the player UI, and to see what parts are available to target.
For more information on the part
attribute, check out the CSS Shadow Parts documentation.
JavaScript API
The webcomponent implements nearly all of the Player API functionality, which can be useful for controlling the player via JavaScript. To access this, first we need to give the player element a unique identifier that can be targeted from JavaScript, like an id
attribute:
<flipnote-player id="player" src="./path/to/some/flipnote.kwz"></flipnote-player>
Then in JavaScript, we can target the player:
var player = document.getElementById('player');
There’s a lot of functionality exposed here, so here’s some of the highlights:
Load and unload Flipnotes
var player = document.getElementById('player');
// Load a Flipnote from a URLplayer.load('./path/to/some/other/flipnote.ppm');// Unloads the current Flipnoteplayer.close();
Playback control
var player = document.getElementById('player');
// Begin animation playbackplayer.play();// Pause animation playbackplayer.pause();// Pause if the animation is playing, else playplayer.togglePlay();
// Jump to the next animation frameplayer.nextFrame();// Jump to the previous animation frameplayer.prevFrame();// Jump to frame 100player.setFrame(100);
Audio control
var player = document.getElementById('player');
// Set volume to 100%player.setVolume(1);// Unmute audioplayer.setMuted(false);// Enable audio equalizer (uses the same EQ settings as Sudomemo)player.setAudioEq(true);
Events
The player element also fires regular DOM events to signal when various actions have happened.
As mentioned in the JavaScript API section, first we need to add a unique identifier to our player element:
<flipnote-player id="player" src="./path/to/some/flipnote.kwz"></flipnote-player>
And then in JavaScript, we can use the standard DOM event listener API to capture player events:
var player = document.getElementById('player');player.addEventListener('play', function() { // do something when playback starts});
A full list of available events can be found on the Player API page.
HTML5 fallback
The player uses WebGL to render the Flipnote’s animation frames, the benefits of which includes faster performance and lower power consumption compared to the HTML5 canvas API. However, there’s typically a limit to how many WebGL instances can be used on the same page (about 8 to 12), and some devices may still not even support it at all. For these cases, the player will automatically downgrade to using a HTML5-backed renderer.
flipnote-image
The <flipnote-image>
element behaves similarly to the standard HTML <img>
element, except it can display a frame from any valid Flipnote Studio .ppm or .kwz animation file directly in the browser. It’s a lot less taxing on resources than the player element, so you can use it to embed lots of Flipnote frames in the same page if you want.
It also works for Flipnote Gallery World comment files (.kwc)
And even Flipnote Studio 3D’s folder icons (!.ico)
Basic usage
After inserting the script into your page, all you need to do is put a <flipnote-image>
tag somewhere in your HTML, and give it a src
attribute pointing to the URL of a Flipnote Studio .ppm or .kwz file:
<flipnote-image src="./path/to/some/flipnote.kwz"></flipnote-image>
Attributes
src
The src
attribute tells the image element what Flipnote it should load, and it should point to the URL of a Flipnote Studio .ppm or .kwz animation file. This attribute be changed at any time to load another Flipnote into the same image.
As with the player element, Flipnotes can also be loaded from other kinds of sources, such as from JavaScript ArrayBuffer
or File
objects.
frame
The Flipnote frame to display as an image, this can be:
- Any numeric value to specify an exact frame index to show
"thumb"
to use the Flipnote’s thumbnail frame"all"
to show the entire animation as a non-interactive animated GIF
cropped
Set this to "true"
to automatically crop out the border around the Flipnote frame.