Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
/**
* Recorder — real-time capture, download, and share for the Mirror page.
*
* The Mirror page draws a 3D avatar to a <canvas> that is driven by the user's
* webcam in real time. This module turns that live canvas into two artifacts a
* user can keep or post:
*
* 1. A short video clip — MediaRecorder over canvas.captureStream(fps),
* optionally muxing a supplied mic/voice audio
* track, auto-stopping at maxDurationMs.
* 2. A still PNG snapshot — canvas.toBlob('image/png').
*
* Plus the plumbing to act on those artifacts: a real browser download (object
* URL + temporary anchor, URL revoked after) and a share-to-X intent window.
*
* Everything here is genuine: real MediaRecorder, real canvas.captureStream,
* real canvas.toBlob. The only timers in this file track *actual* elapsed wall
* time (the max-duration cutoff and the onTick UI clock) — there is no
* simulated progress, no setTimeout-faked loading.
*
* State machine (surfaced through `onState`):
*
* idle ──start()──▶ recording ──stop()/auto──▶ stopping ──blob──▶ ready
* ▲ │ │
* └──────cancel()───────┘ next start() ─────────┘
*
* Usage:
*
* const rec = new Recorder({ fps: 30, maxDurationMs: 15000 });
* rec.onState = (s) => updateButton(s);
* rec.onTick = (ms) => updateTimer(ms);
* rec.start(canvas, { audioStream: micStream }); // micStream optional
* // ...later...
* const blob = await rec.stop();
* if (blob) downloadBlob(blob, suggestedFilename('three-ws-mirror', 'webm'));
*
* // Still image + share:
* const png = await snapshotPNG(canvas);
* downloadBlob(png, suggestedFilename('three-ws-mirror', 'png'));
* shareToX({ text: 'My avatar on three.ws', url: 'https://three.ws', hashtags: ['threews'] });
*
* Pure module: no DOM scaffolding beyond the throwaway <a> used for download
* and window.open for share. No CSS. ES module, named exports.
*/
// MediaRecorder mimeTypes we'll try, best-first. The first one the browser
// reports as supported wins.
const MIME_CANDIDATES = [
'video/webm;codecs=vp9',
'video/webm;codecs=vp8',
'video/webm',
'video/mp4',
];
// How often onTick fires while recording (~4x/sec).
const TICK_INTERVAL_MS = 250;
/**
* Picks the best MediaRecorder mimeType the current browser supports.
* @returns {string} a supported mimeType, or '' to let the browser choose.
*/
function pickMimeType() {
if (typeof MediaRecorder === 'undefined' ||
typeof MediaRecorder.isTypeSupported !== 'function') {
return '';
}
for (const mime of MIME_CANDIDATES) {
if (MediaRecorder.isTypeSupported(mime)) return mime;
}
return '';
}
/**
* True when this environment can actually record a canvas.
* @returns {boolean}
*/
function detectSupport() {
if (typeof MediaRecorder === 'undefined') return false;
if (typeof HTMLCanvasElement === 'undefined') return false;
if (typeof HTMLCanvasElement.prototype.captureStream !== 'function') return false;
return true;
}
export class Recorder {
/**
* @param {{ fps?: number, maxDurationMs?: number }} [opts]
*/
constructor(opts = {}) {
this.fps = Number.isFinite(opts.fps) && opts.fps > 0 ? opts.fps : 30;
this.maxDurationMs = Number.isFinite(opts.maxDurationMs) && opts.maxDurationMs > 0
? opts.maxDurationMs
: 30000;
// Assignable callbacks — default to no-ops so callers can skip either.
this.onState = () => {};
this.onTick = () => {};
this._state = 'idle';
this._recorder = null;
this._stream = null;
this._chunks = [];
this._mimeType = '';
this._startedAt = 0;
this._maxTimer = null;
this._tickTimer = null;
// Pending stop() promise resolver, set while a stop is in flight.
this._stopResolve = null;
}
/** @returns {string} current state: 'idle'|'recording'|'stopping'|'ready' */
get state() {
return this._state;
}
/** @returns {boolean} true while actively recording. */
get recording() {
return this._state === 'recording';
}
/** @returns {boolean} whether recording is possible in this environment. */
get supported() {
return detectSupport();
}
/**
* Begin recording the given canvas.
*
* @param {HTMLCanvasElement} canvas
* @param {{ audioStream?: MediaStream }} [opts] optional mic/voice stream to mux.
* @throws {Error} when unsupported, given a bad canvas, or already recording.
*/
start(canvas, opts = {}) {
if (!this.supported) {
throw new Error('Recording is not supported in this browser (MediaRecorder or canvas.captureStream unavailable).');
}
if (!canvas || typeof canvas.captureStream !== 'function') {
throw new Error('Recorder.start requires an HTMLCanvasElement with captureStream support.');
}
if (this._state === 'recording' || this._state === 'stopping') {
throw new Error('Recorder is already running. Stop or cancel before starting again.');
}
// Clean any leftover state from a prior 'ready' cycle.
this._teardownTimers();
this._chunks = [];
this._stopResolve = null;
const videoStream = canvas.captureStream(this.fps);
const videoTracks = videoStream.getVideoTracks();
let stream = videoStream;
const audioStream = opts.audioStream;
if (audioStream && typeof audioStream.getAudioTracks === 'function') {
const audioTracks = audioStream.getAudioTracks();
if (audioTracks.length > 0) {
stream = new MediaStream([...videoTracks, ...audioTracks]);
}
}
this._mimeType = pickMimeType();
const recorderOptions = this._mimeType ? { mimeType: this._mimeType } : undefined;
let recorder;
try {
recorder = new MediaRecorder(stream, recorderOptions);
} catch (err) {
// Fall back to default options if the chosen mimeType was rejected.
recorder = new MediaRecorder(stream);
this._mimeType = '';
}
// Honor whatever the recorder actually committed to, when exposed.
if (recorder.mimeType) this._mimeType = recorder.mimeType;
recorder.ondataavailable = (event) => {
if (event.data && event.data.size > 0) {
this._chunks.push(event.data);
}
};
recorder.onstop = () => this._finalize();
recorder.onerror = () => {
// A recorder error mid-capture: salvage whatever chunks exist by
// finalizing rather than leaving the caller hanging.
this._finalize();
};
this._stream = stream;
this._recorder = recorder;
this._startedAt = Date.now();
// requestData cadence isn't required — onstop flushes a final chunk —
// but a timeslice guarantees periodic chunks for long clips.
recorder.start(1000);
this._setState('recording');
this._tickTimer = setInterval(() => {
this.onTick(Date.now() - this._startedAt);
}, TICK_INTERVAL_MS);
this._maxTimer = setTimeout(() => {
this._maxTimer = null;
// Auto-stop at the duration cap; ignore the returned promise here,
// any pending stop() awaiter is still resolved through _finalize.
this.stop();
}, this.maxDurationMs);
}
/**
* Stop recording and resolve to the assembled Blob.
* Safe to call when not recording — resolves null.
*
* @returns {Promise<Blob|null>}
*/
stop() {
if (this._state !== 'recording') {
return Promise.resolve(null);
}
this._setState('stopping');
this._teardownTimers();
return new Promise((resolve) => {
this._stopResolve = resolve;
try {
if (this._recorder && this._recorder.state !== 'inactive') {
this._recorder.stop();
} else {
this._finalize();
}
} catch (err) {
// If stop() throws, still finalize so the awaiter resolves.
this._finalize();
}
});
}
/**
* Discard an in-progress recording without producing a blob.
* Resolves any pending stop() awaiter with null and returns to 'idle'.
*/
cancel() {
const wasActive = this._state === 'recording' || this._state === 'stopping';
this._teardownTimers();
const recorder = this._recorder;
if (recorder) {
recorder.ondataavailable = null;
recorder.onstop = null;
recorder.onerror = null;
try {
if (recorder.state !== 'inactive') recorder.stop();
} catch (err) {
// Already inactive or detached — nothing to recover.
}
}
this._releaseStream();
this._recorder = null;
this._chunks = [];
this._mimeType = '';
const resolve = this._stopResolve;
this._stopResolve = null;
if (wasActive) this._setState('idle');
if (resolve) resolve(null);
}
// --- internals ---------------------------------------------------------
/**
* Assemble collected chunks into a Blob, settle pending stop(), and move to
* 'ready'. Idempotent: guarded so a recorder error + onstop don't double-fire.
*/
_finalize() {
if (this._state !== 'stopping' && this._state !== 'recording') {
// Already finalized or cancelled.
return;
}
this._teardownTimers();
const type = this._mimeType || 'video/webm';
const blob = this._chunks.length > 0
? new Blob(this._chunks, { type })
: null;
this._chunks = [];
this._releaseStream();
this._recorder = null;
const resolve = this._stopResolve;
this._stopResolve = null;
this._setState('ready');
if (resolve) resolve(blob);
}
/** Stop and release the captured stream's tracks. */
_releaseStream() {
if (this._stream) {
for (const track of this._stream.getTracks()) {
try {
track.stop();
} catch (err) {
// Track already ended.
}
}
this._stream = null;
}
}
/** Clear both the max-duration cutoff and the onTick interval. */
_teardownTimers() {
if (this._maxTimer !== null) {
clearTimeout(this._maxTimer);
this._maxTimer = null;
}
if (this._tickTimer !== null) {
clearInterval(this._tickTimer);
this._tickTimer = null;
}
}
/**
* @param {'idle'|'recording'|'stopping'|'ready'} next
*/
_setState(next) {
if (this._state === next) return;
this._state = next;
this.onState(next);
}
}
/**
* Capture a still PNG of the canvas.
*
* @param {HTMLCanvasElement} canvas
* @returns {Promise<Blob>} a PNG blob.
*/
export function snapshotPNG(canvas) {
return new Promise((resolve, reject) => {
if (!canvas || typeof canvas.toBlob !== 'function') {
reject(new Error('snapshotPNG requires an HTMLCanvasElement with toBlob support.'));
return;
}
try {
canvas.toBlob((blob) => {
if (blob) {
resolve(blob);
} else {
reject(new Error('Failed to encode canvas to PNG (toBlob returned null).'));
}
}, 'image/png');
} catch (err) {
// canvas.toBlob throws SecurityError on a tainted (cross-origin) canvas.
reject(err instanceof Error ? err : new Error(String(err)));
}
});
}
/**
* Trigger a browser download of a blob via a temporary object URL + anchor.
* The object URL is revoked after the click to avoid leaking memory.
*
* @param {Blob} blob
* @param {string} filename
*/
export function downloadBlob(blob, filename) {
if (!blob) {
throw new Error('downloadBlob requires a Blob.');
}
const url = URL.createObjectURL(blob);
const anchor = document.createElement('a');
anchor.href = url;
anchor.download = filename || 'download';
anchor.rel = 'noopener';
anchor.style.display = 'none';
document.body.appendChild(anchor);
anchor.click();
document.body.removeChild(anchor);
// Revoke on the next tick so the navigation has committed.
setTimeout(() => URL.revokeObjectURL(url), 0);
}
/**
* Open X's tweet-intent composer in a new tab, pre-filled with the supplied copy.
* The caller supplies all text — nothing is defaulted on their behalf.
*
* @param {{ text?: string, url?: string, hashtags?: string[] }} params
* @returns {Window|null} the opened window, or null if the browser blocked it.
*/
export function shareToX({ text, url, hashtags } = {}) {
const params = new URLSearchParams();
if (text) params.set('text', text);
if (url) params.set('url', url);
if (Array.isArray(hashtags) && hashtags.length > 0) {
// X expects bare, comma-joined tags (no leading '#').
const tags = hashtags
.map((tag) => String(tag).replace(/^#/, '').trim())
.filter(Boolean);
if (tags.length > 0) params.set('hashtags', tags.join(','));
}
const intentUrl = `https://twitter.com/intent/tweet?${params.toString()}`;
return window.open(intentUrl, '_blank', 'noopener');
}
/**
* Build a timestamped filename using local time.
*
* @param {string} [prefix='three-ws-mirror']
* @param {string} [ext='webm']
* @returns {string} e.g. "three-ws-mirror-20260619-143005.webm"
*/
export function suggestedFilename(prefix = 'three-ws-mirror', ext = 'webm') {
const now = new Date();
const pad = (n) => String(n).padStart(2, '0');
const date = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`;
const time = `${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
const cleanExt = String(ext).replace(/^\./, '');
return `${prefix}-${date}-${time}.${cleanExt}`;
}