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.mdindex 1ed80d3..c43ba93 100644--- a/API.md+++ b/API.md@@ -193,6 +193,18 @@ tracking.calibrate() // the user's current pose becomes "facing front" (it alsotracking.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.jsnew file mode 100644index 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.htmlindex 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 belowasync 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.messagecontrols(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 = nullbutton('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.htmlindex 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) returncurrent = idfor (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 meanwhilename.textContent = m.nameexprs = m.expressions; next = -1@@ -66,7 +69,7 @@}// a click on the stage: the next expression, then neutral againdocument.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.htmlindex 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 sameconst 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 againlet i = -1diff --git a/example/loading.js b/example/loading.jsnew file mode 100644index 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.htmlindex 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 = nulldocument.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.htmlindex 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 = nulldocument.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>