Skip to content

A lightweight 2.5D character player for the web, with lip sync and webcam face tracking.

Examples: Refined Nana by default; the camera explains itself first, and a refused or missing camera gets a short note and a demo motion

LivLivaeeb8e49b7fd
diff --git a/API.md b/API.md
index 1ed80d3..c43ba93 100644
--- a/API.md
+++ b/API.md
@@ -193,6 +193,18 @@ tracking.calibrate() // the user's current pose becomes "facing front" (it also
tracking.stop()
```
+A refused or missing camera rejects with the browser's error. `trace: 'synth'` plays a demo motion and asks for no camera,
+which makes a good fallback (`example/camera.js` does all of this):
+
+```js
+const tracking = await startFaceTracking(player).catch((e) => {
+ if (e.name === 'NotAllowedError') note('Camera not allowed. Turn it on from the icon in the address bar.')
+ else if (e.name === 'NotFoundError') note('No camera found.')
+ else console.error(e)
+ return startFaceTracking(player, { trace: 'synth' })
+})
+```
+
| option | default | |
|---|---|---|
| `mirror` | `true` | move like a mirror image |
diff --git a/example/camera.js b/example/camera.js
new file mode 100644
index 0000000..5d29e4e
--- /dev/null
+++ b/example/camera.js
@@ -0,0 +1,83 @@
+// The camera button of the example pages. A click says what the camera is for before the browser asks; a camera that is
+// refused or missing gets a short note and a demo motion, which needs no camera, instead of an error.
+const INTRO = 'The character follows your face through your camera. Images stay on your device.'
+const NOTES = {
+ NotAllowedError: 'Camera not allowed. Turn it on from the icon in the address bar, then try again.',
+ NotFoundError: 'No camera found.',
+ NotReadableError: 'The camera is busy in another app.',
+}
+
+const style = document.createElement('style')
+style.textContent = `
+ .camera-card { position: fixed; z-index: 2; box-sizing: border-box; width: min(320px, calc(100vw - 24px)); padding: 12px;
+ border-radius: 12px; background: #2d303c; color: #eef; font: 14px/1.4 system-ui, sans-serif; box-shadow: 0 6px 24px #0006 }
+ .camera-card p { margin: 0 0 10px }
+ .camera-card div { display: flex; flex-wrap: wrap; gap: 6px }
+ .camera-card button { font: inherit; padding: 6px 11px; border: 0; border-radius: 8px; background: #ffffff1c; color: inherit; cursor: pointer }
+ .camera-card button:first-child { background: #ff4d5e }`
+document.head.append(style)
+
+/** Makes `button` start and stop face tracking on `player`, saying how it goes in `status`. `.running` is the tracking. */
+export function cameraButton(button, player, status) {
+ let running = null, card = null, before = ''
+
+ const closeCard = () => { card?.remove(); card = null; removeEventListener('keydown', onKey) }
+ const onKey = (e) => { if (e.key === 'Escape') closeCard() }
+
+ function openCard(text, again) {
+ closeCard()
+ card = document.createElement('div')
+ card.className = 'camera-card'
+ card.setAttribute('role', 'dialog')
+ card.setAttribute('aria-label', 'Camera')
+ const line = document.createElement('p'), row = document.createElement('div')
+ line.textContent = text
+ for (const [label, trace] of [[again ? 'Try again' : 'Turn on camera', undefined], ['Show a demo', 'synth']]) {
+ const b = document.createElement('button')
+ b.textContent = label
+ b.onclick = () => start(trace)
+ row.append(b)
+ }
+ card.append(line, row)
+ document.body.append(card)
+ const at = button.getBoundingClientRect()
+ card.style.top = `${at.bottom + 8}px`
+ card.style.left = `${Math.max(12, Math.min(at.left, innerWidth - card.offsetWidth - 12))}px`
+ row.firstChild.focus()
+ addEventListener('keydown', onKey)
+ }
+
+ async function start(trace) {
+ closeCard()
+ before ||= status.textContent
+ button.disabled = true
+ let asking = true // the face model goes on downloading after a refusal: its progress is no news then
+ try {
+ const { startFaceTracking } = await import('../dist/tracking.js')
+ running = await startFaceTracking(player, {
+ trace,
+ onProgress: (s) => { if (asking) status.textContent = s.step === 'download' ? `Face model ${Math.round(s.progress * 100)}%` : `${s.step}…` },
+ })
+ asking = false
+ status.textContent = trace ? 'Demo motion, no camera in use' : 'Camera on'
+ } catch (e) {
+ asking = false
+ status.textContent = before
+ if (!NOTES[e.name]) console.error('Face tracking could not start:', e)
+ openCard(NOTES[e.name] || 'Face tracking could not start. The console has the details.', true)
+ }
+ button.disabled = false
+ button.setAttribute('aria-pressed', String(!!running))
+ }
+
+ button.onclick = () => {
+ if (card) return closeCard()
+ if (!running) return openCard(INTRO)
+ running.stop()
+ running = null
+ status.textContent = before
+ before = ''
+ button.setAttribute('aria-pressed', 'false')
+ }
+ return { get running() { return running } }
+}
diff --git a/example/demo.html b/example/demo.html
index 50726ef..91e18de 100644
--- a/example/demo.html
+++ b/example/demo.html
@@ -19,6 +19,8 @@
<script type="module">
import { Player } from '../dist/index.js'
+ import { cameraButton } from './camera.js'
+ import { loading } from './loading.js'
const player = new Player(document.getElementById('stage'))
const bar = document.getElementById('bar'), status = document.getElementById('status')
@@ -30,7 +32,8 @@
// a model: a featured character, ?model=<URL of a model.json or its folder>, or a folder picked below
async function show(source) {
- status.textContent = 'Loading…'
+ status.textContent = ''
+ const done = loading(document.body, typeof source === 'string' && source.endsWith('/') ? `${source}avatar.webp` : null)
try {
const m = await player.load(source)
status.textContent = `${m.name} · ${m.format} ${m.version} · mark: ${m.watermark ?? 'none'}${m.meta?.license ? ` · ${m.meta.license.id}` : ''}`
@@ -39,6 +42,7 @@
status.textContent = e.message
controls(null)
}
+ done()
}
function controls(m) {
@@ -56,7 +60,7 @@
exprs.forEach((o) => o.setAttribute('aria-pressed', String(o === b)))
}))
for (const a of ['nod', 'shake', 'tilt', 'hop']) button(a, () => player.act(a))
- let mic = null, cam = null
+ let mic = null
button('microphone', async (b) => {
if (mic) { mic.stop(); mic = null } else {
const { startLipSync } = await import('../dist/voice.js')
@@ -64,18 +68,10 @@
}
b.setAttribute('aria-pressed', String(!!mic))
})
- button('camera', async (b) => {
- if (cam) { cam.stop(); cam = null } else {
- const { startFaceTracking } = await import('../dist/tracking.js')
- cam = await startFaceTracking(player, {
- onProgress: (s) => { status.textContent = s.step === 'download' ? `Face model ${Math.round(s.progress * 100)}%` : `${s.step}…` },
- }).catch((e) => { status.textContent = e.message; return null })
- if (cam) status.textContent = 'Camera on'
- }
- b.setAttribute('aria-pressed', String(!!cam))
- })
+ window.camera?.running?.stop() // a new model, new buttons: the old button's tracking ends with it
+ window.camera = cameraButton(button('camera'), player, status)
}
- show(new URLSearchParams(location.search).get('model') || '../characters/k01/')
+ show(new URLSearchParams(location.search).get('model') || '../characters/d03ft/')
</script>
</html>
diff --git a/example/gallery.html b/example/gallery.html
index a2392f4..f62455b 100644
--- a/example/gallery.html
+++ b/example/gallery.html
@@ -7,6 +7,7 @@
html, body { margin: 0; min-height: 100%; background: #f4f2ef; font: 14px system-ui, sans-serif; color: #222 }
main { max-width: 900px; margin: 0 auto; padding: 16px }
.stage { background: #fff; border-radius: 16px; overflow: hidden }
+ .view { position: relative }
canvas { display: block; width: 100%; height: min(70vh, 640px); cursor: pointer }
.bar { display: flex; flex-wrap: wrap; align-items: center; gap: 6px; padding: 10px 14px }
.bar b { margin-right: auto; font-size: 15px }
@@ -19,16 +20,17 @@
</style>
<main>
<div class="stage">
- <canvas id="stage"></canvas>
+ <div class="view" id="view"><canvas id="stage"></canvas></div>
<div class="bar" id="bar"><b id="name"></b></div>
</div>
<ul class="cast" id="cast"></ul>
</main>
<script type="module">
import { Player } from '../dist/index.js'
+ import { loading } from './loading.js'
// All the featured characters: one plays on the stage (one player, one WebGL context), the rest wait as their
- // pictures; a click on one puts it on the stage. ?id=<id> starts with that one; ?demo=1 plays expressions and
+ // pictures; a click on one puts it on the stage. ?id=<id> starts with that one (else Refined Nana); ?demo=1 plays expressions and
// actions by itself and moves to the next character now and then (for recording the README's GIF)
const FIRST = ['p01', 'p02', 'd03', 'd03ft', 'p03', 'k01', 'k02', 's01', 'v07']
const q = new URLSearchParams(location.search), demo = q.get('demo') === '1'
@@ -55,7 +57,8 @@
if (id === current) return
current = id
for (const [k, b] of buttons) b.setAttribute('aria-pressed', String(k === id))
- const m = await player.load(`../characters/${id}/`)
+ const done = loading(document.getElementById('view'), `../characters/${id}/avatar.webp`)
+ const m = await player.load(`../characters/${id}/`).finally(done)
if (id !== current) return // another was picked meanwhile
name.textContent = m.name
exprs = m.expressions; next = -1
@@ -66,7 +69,7 @@
}
// a click on the stage: the next expression, then neutral again
document.getElementById('stage').onclick = () => { next = next + 1 < exprs.length ? next + 1 : -1; player.setExpression(exprs[next]?.id ?? null) }
- await show(cast.some((c) => c.id === q.get('id')) ? q.get('id') : cast[0].id)
+ await show(cast.some((c) => c.id === q.get('id')) ? q.get('id') : 'd03ft')
if (demo) {
const acts = ['nod', 'tilt', 'shake', 'hop', 'shy']
diff --git a/example/index.html b/example/index.html
index 4f74ad3..645fd7f 100644
--- a/example/index.html
+++ b/example/index.html
@@ -5,12 +5,14 @@
<title>LivLiv Player: minimal</title>
<style>html, body { margin: 0; height: 100%; background: #20222b } canvas { display: block; width: 100%; height: 100% }</style>
<canvas id="stage"></canvas>
+<p id="wait" style="position:fixed;inset:45% 0 auto;margin:0;color:#eef;font:14px system-ui,sans-serif;text-align:center">Loading…</p>
<script type="module">
import { Player } from '../dist/index.js'
// a featured character; your own export works the same
const player = new Player(document.getElementById('stage'))
- const model = await player.load('../characters/k01/')
+ const model = await player.load('../characters/d03ft/')
+ document.getElementById('wait').remove()
// each click shows the next expression, then neutral again
let i = -1
diff --git a/example/loading.js b/example/loading.js
new file mode 100644
index 0000000..7ffec32
--- /dev/null
+++ b/example/loading.js
@@ -0,0 +1,17 @@
+// The example pages' wait for a character.
+/** A picture and "Loading…" over the page until `done()`, shown only if the load takes a moment. */
+export function loading(parent, picture) {
+ const box = document.createElement('div')
+ box.style.cssText = 'position:absolute;inset:0;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:8px;pointer-events:none'
+ if (picture) {
+ const img = new Image(96, 96)
+ img.alt = ''
+ img.style.borderRadius = '12px'
+ img.onerror = () => img.remove()
+ img.src = picture
+ box.append(img)
+ }
+ box.append('Loading…')
+ const later = setTimeout(() => parent.append(box), 150)
+ return () => { clearTimeout(later); box.remove() }
+}
diff --git a/example/png.html b/example/png.html
index 4916bfb..dcf0554 100644
--- a/example/png.html
+++ b/example/png.html
@@ -22,6 +22,7 @@
<script type="module">
import { BodyPlayer } from '../dist/body.js'
import { PngBody } from '../dist/png.js'
+ import { cameraButton } from './camera.js'
// a PNGTuber: pictures named closed, open, and if you have them blink and blink-open (any image type). With none
// picked, a face drawn here stands in
@@ -53,7 +54,7 @@
document.getElementById('pick').onchange = (e) => e.target.files.length && show(e.target.files)
show({ closed: await face(true, false), open: await face(true, true), blink: await face(false, false), 'blink-open': await face(false, true) })
- let mic = null, cam = null
+ let mic = null
document.getElementById('mic').onclick = async (e) => {
if (mic) { mic.stop(); mic = null } else {
const { startLipSync } = await import('../dist/voice.js')
@@ -61,12 +62,6 @@
}
e.target.setAttribute('aria-pressed', String(!!mic))
}
- document.getElementById('cam').onclick = async (e) => {
- if (cam) { cam.stop(); cam = null } else {
- const { startFaceTracking } = await import('../dist/tracking.js')
- cam = await startFaceTracking(player).catch((err) => { status.textContent = err.message; return null })
- }
- e.target.setAttribute('aria-pressed', String(!!cam))
- }
+ window.camera = cameraButton(document.getElementById('cam'), player, status)
</script>
</html>
diff --git a/example/vrm.html b/example/vrm.html
index dfd1986..3dd25d1 100644
--- a/example/vrm.html
+++ b/example/vrm.html
@@ -28,6 +28,7 @@
<script type="module">
import { BodyPlayer } from '../dist/body.js'
import { VrmBody } from '../dist/vrm.js'
+ import { cameraButton } from './camera.js'
const player = new BodyPlayer(document.getElementById('stage'), new VrmBody())
const status = document.getElementById('status'), bar = document.getElementById('bar')
@@ -52,7 +53,7 @@
const url = new URLSearchParams(location.search).get('model')
if (url) show(url)
- let mic = null, cam = null
+ let mic = null
document.getElementById('mic').onclick = async (e) => {
if (mic) { mic.stop(); mic = null } else {
const { startLipSync } = await import('../dist/voice.js')
@@ -60,12 +61,6 @@
}
e.target.setAttribute('aria-pressed', String(!!mic))
}
- document.getElementById('cam').onclick = async (e) => {
- if (cam) { cam.stop(); cam = null } else {
- const { startFaceTracking } = await import('../dist/tracking.js')
- cam = await startFaceTracking(player).catch((err) => { status.textContent = err.message; return null })
- }
- e.target.setAttribute('aria-pressed', String(!!cam))
- }
+ window.camera = cameraButton(document.getElementById('cam'), player, status)
</script>
</html>