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.
Installing the web component build is very similar to the usual installation steps listed on the Getting Started page, except we import a different file that has the additional web component code included.
<script src="https://cdn.jsdelivr.net/npm/flipnote.js@5/dist/flipnote.webcomponent.min.js"></script>
// with the require() function:
const flipnote = require('flipnote.js/flipnote.webcomponent.js');
// or with the es6 import syntax:
import flipnote from 'flipnote.js/flipnote.webcomponent.js';
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:
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!
srcThe 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.
controlsThe 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>
cropBorderSet 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.
dsiLibrarySet dsiLibrary="true" to enable special processing for KWZs from Nintendo DSi Library. This value can not be updated after a Flipnote is loaded.
bgmPredictorSome 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.
bgmStepIndexLike 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.
sePredictorsLike bgmPredictor, the value of sePredictors will provide the initial ADPCM predictor values when decoding each sound effect track, as a comma-seperated 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.
seStepIndicesLike bgmStepIndex, the value of seStepIndices will provide the initial ADPCM step index values when decoding each sound effect track, as a comma-seperated 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.
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;
}
| CSS variable | Default value | Use |
|---|---|---|
--flipnote-player-font-family |
sans-serif |
Font to use for any player UI text |
--flipnote-player-controls-background |
none |
Background color for the controls area |
--flipnote-player-button-background |
#FFD3A6 |
Background color for any player buttons |
--flipnote-player-button-color |
#F36A2D |
Text and icon color for any player buttons |
This isn't super fleshed-out, so if you need more styling options for your use-case feel free to open an issue to request something!
The webcomponent implements nearly all of the Player API functionality, which can be useful for controling 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:
var player = document.getElementById('player');
// Load a Flipnote from a URL
player.load('./path/to/some/other/flipnote.ppm');
// Unloads the current Flipnote
player.close();
var player = document.getElementById('player');
// Begin animation playback
player.play();
// Pause animation playback
player.pause();
// Pause if the animation is playing, else play
player.togglePlay();
// Jump to the next animation frame
player.nextFrame();
// Jump to the previous animation frame
player.prevFrame();
// Jump to frame 100
player.setFrame(100);
var player = document.getElementById('player');
// Set volume to 100%
player.setVolume(1);
// Unmute audio
player.setMuted(false);
// Enable audio qualizer (uses the same EQ settings as Sudomemo)
player.setAudioEq(true);
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.
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.
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)
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>
srcThe 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.
frameThe Flipnote frame to display as an image, this can be:
"thumb" to use the Flipnote's thumbnail frame"all" to show the entire animation as a non-interactive animated GIFcroppedSet this to "true" to automatically crop out the border around the Flipnote frame.