Masko player

The Masko player puts your mascot in a website or an app, with its transparency, on the web, React, iPhone, iPad, Mac, React Native, Flutter and Android. Give it one animation and it loops it. Give it a released canvas and it switches clips by itself: your app only says what is happening, with set and fire.

This is Spike, playing in the Masko player. Hover him, grab him or press a button: the calls your app would send to the player show under him.

// The calls your app sends show here.

Two ways to play#

Install#

Web#

• It runs in Chrome and Edge 87, Firefox 79 and Safari 15 (iOS 15) or later.
• The element sets the mascot's size. Without a height, the mascot is square and as wide as the element.
• The script tag defines window.MaskoPlayer; it is a classic script, not a module.
• It runs in Electron apps too, including in a transparent window as a desktop mascot: see the Electron example.
• With a Content Security Policy, allow 'wasm-unsafe-eval' in script-src, your clip host in connect-src, and your clip host and blob: in media-src. The web README lists every rule and the Vite setting.

iPhone, iPad and Mac#

In Xcode, choose File > Add Package Dependencies, enter https://github.com/masko-ai/masko-player, choose Up to Next Major Version from 0.1.9 and add the MaskoPlayer product to your app target. It runs on iOS 15, macOS 13, Mac Catalyst 15 and visionOS 1 or later. Show it with MaskoView in SwiftUI or MaskoPlayerView in UIKit and AppKit. The Apple README has every call.

React Native and Expo#

npm install @masko/player-react-native
npx expo run:ios   # or: npx expo run:android

The package is an Expo module with the Swift and Android players inside, for Expo SDK 54 (React Native 0.81, new architecture), iOS 15.1 and Android 7 (API 24) or later. It has native code, so build the app after installing it. A bare React Native app installs Expo modules first (npx install-expo-modules) and runs pod install in ios/. On Android, keep the ABIs the player is built for with reactNativeArchitectures=armeabi-v7a,arm64-v8a,x86_64 in android/gradle.properties. The React Native README has every prop and call.

Flutter#

flutter pub add masko_player

The package carries the Swift and Android players, for Flutter 3.24 or later, iOS 15 and Android 7 (API 24) or later. iOS apps build it with Swift Package Manager or CocoaPods: set the Runner's iOS deployment target to 15.0, and platform :ios, '15.0' in ios/Podfile when the app uses CocoaPods. Show the mascot with MaskoView and drive it with a MaskoController. The Flutter README has every option and call.

Android#

// settings.gradle.kts: repositories { google(); mavenCentral() }
dependencies {
    implementation("ai.masko:player:0.1.11")
}

ai.masko:player is on Maven Central, for Android 7 (API 24) and Java 17 or later. Keep the ABIs it is built for with abiFilters += listOf("arm64-v8a", "armeabi-v7a", "x86_64") in defaultConfig.ndk. Show it with MaskoPlayerView. The Android README has every call.

What it handles#

• Transparency everywhere. It plays the file each platform shows with transparency: HEVC on Safari and Apple devices, WebM in other browsers and the stacked MP4 on Android. Apps that ask for it get the stacked AV1 file, two to three times lighter (file sizes).
• No flicker. The next clip is shown only once its first frame is ready, and a move waits for the end of the loop on screen, so it starts from the same frame.
• The page or app around it. It preloads the next clips, pauses while the page is hidden or the app is in the background, and shows a tap-to-play button when the browser blocks autoplay.
• Sound. A clip's own voice is heard by default; setSound(false) on the web or sound set to false on Apple, Android, React Native and Flutter mutes it. Browsers allow sound only after the person's first click or key press on the page; until then the player plays muted, and the voice is heard from the next clip or loop.

The player is open source (MIT) at github.com/masko-ai/masko-player: one Rust engine runs the canvas rules, with a player for each platform. The rulebook gives every rule.