@rapidmx/meet-plugin 0.5.0 → 0.8.0

package/apps/shared/media/filters/VideoFilterProcessor.ts

@@ -0,0 +1,383 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Turns the camera's `MediaStreamTrack` into a *filtered* one: frames from the camera are drawn onto a canvas, put
+ * through the chosen filters, and the canvas's `captureStream()` track is what the rest of the app sends to the call.
+ * `useLocalMedia()` owns one of these while any filter is on and swaps it in for the camera track, so the lobby
+ * preview, the peer connections and the WebSocket relay all get the filtered picture without knowing about it.
+ *
+ * Per frame: the background (untouched, or blurred / replaced behind the person-segmentation mask), then the colour
+ * effect over the whole picture, then the face accessory on top - see `filterTypes.ts`.
+ *
+ * - **Fails closed.** A participant who asked for a hidden background must never be shown with their real one - not
+ * while the segmentation model is still loading, and not if it can't be loaded. Until the mask is available the frame
+ * is the background alone (the blurred or replacement picture, no person), and `onStatus` reports the load and any
+ * failure so the UI can say why. Accessories don't matter that way: without the face model there simply is no accessory.
+ * - **Timing.** Frames are driven by a timer rather than `requestAnimationFrame`, which stops entirely in a
+ * background tab - the call would freeze for everyone else the moment the participant switched to another window.
+ * Browsers still slow a background tab's timers, so a filtered picture can drop to a low frame rate there.
+ *
+ * Everything browser-facing (canvases, the video element, the models) comes in through `deps`, so the tests drive a
+ * processor with fakes.
+ */
+import { type FaceGeometry, type FaceLandmark, drawAccessory, faceGeometry } from "./accessories.js";
+import { type Accessory, type VideoFilters, needsFace, needsSegmentation } from "./filterTypes.js";
+import { type FaceTracker, type PersonMask, type PersonSegmenter, createFaceTracker, createPersonSegmenter } from "./mlModels.js";
+import { applyGrayscale, applyNightVision, applySepia, maskToAlpha } from "./pixelEffects.js";
+
+/** A picture to show behind the participant. */
+export interface BackgroundPicture {
+    source: CanvasImageSource;
+    width: number;
+    height: number;
+}
+
+export interface FilterStatus {
+    /** A model the current filters need is still downloading. */
+    loading: boolean;
+    /** Why a filter isn't fully working, ready to show - `null` when all is well. */
+    error: string | null;
+}
+
+export interface ProcessorDeps {
+    createCanvas(): HTMLCanvasElement;
+    createVideo(): HTMLVideoElement;
+    createSegmenter(assetsUrl?: string): Promise<PersonSegmenter>;
+    createFaceTracker(assetsUrl?: string): Promise<FaceTracker>;
+    now(): number;
+}
+
+export interface VideoFilterProcessorOptions {
+    /** The camera's track. The processor only reads it - stopping it stays with whoever owns it. */
+    source: MediaStreamTrack;
+    filters: VideoFilters;
+    backgroundImage?: BackgroundPicture | null;
+    /** Where the models are hosted, when not on the default CDN - see `mlModels.ts`. */
+    assetsUrl?: string;
+    onStatus?: (status: FilterStatus) => void;
+    frameRate?: number;
+    deps?: Partial<ProcessorDeps>;
+}
+
+const DEFAULT_FRAME_RATE = 30;
+/** The background is blurred by drawing the frame at 1/this size and scaling it back up. */
+const BLUR_DIVISOR = 12;
+/** The picture is pixelated into about this many blocks across. */
+const PIXEL_BLOCKS = 80;
+/** How many frames in a row without a detected face before the accessory is taken off - a face is briefly lost when
+ * the head turns, and the accessory shouldn't flicker for that. */
+const FACE_HOLD_FRAMES = 6;
+
+const SEGMENTATION_ERROR =
+    "The background effect couldn't be loaded, so your background stays hidden. Turn the effect off to show your camera.";
+const FACE_ERROR = "The face effect couldn't be loaded.";
+const RENDER_ERROR = "Video effects stopped working.";
+
+type ModelState = "idle" | "loading" | "ready" | "failed";
+
+interface Layer {
+    canvas: HTMLCanvasElement;
+    ctx: CanvasRenderingContext2D;
+}
+
+const PIXEL_EFFECTS = { bw: applyGrayscale, sepia: applySepia, "night-vision": applyNightVision };
+
+const DEFAULT_DEPS: ProcessorDeps = {
+    createCanvas: () => document.createElement("canvas"),
+    createVideo: () => document.createElement("video"),
+    createSegmenter: createPersonSegmenter,
+    createFaceTracker,
+    now: () => performance.now(),
+};
+
+function context2d(canvas: HTMLCanvasElement): CanvasRenderingContext2D {
+    const ctx = canvas.getContext("2d", { willReadFrequently: true });
+    if (!ctx) {
+        throw new Error("This browser can't draw video effects.");
+    }
+    return ctx;
+}
+
+export class VideoFilterProcessor {
+    /** The filtered video - what to send in place of the camera's track. */
+    readonly track: MediaStreamTrack;
+
+    private readonly deps: ProcessorDeps;
+    private readonly assetsUrl?: string;
+    private readonly onStatus?: (status: FilterStatus) => void;
+    private readonly interval: number;
+    private readonly video: HTMLVideoElement;
+    private readonly canvas: HTMLCanvasElement;
+    private readonly ctx: CanvasRenderingContext2D;
+    private readonly layers = new Map<string, Layer>();
+
+    private filters: VideoFilters;
+    private backgroundImage: BackgroundPicture | null;
+    private stopped = false;
+    private timer: ReturnType<typeof setTimeout> | undefined;
+
+    private segmenter: PersonSegmenter | null = null;
+    private segmenterState: ModelState = "idle";
+    private faceTracker: FaceTracker | null = null;
+    private faceState: ModelState = "idle";
+    private lastFace: FaceLandmark[] | null = null;
+    private framesWithoutFace = 0;
+    private maskImage: ImageData | null = null;
+    private renderFailed = false;
+    private status: FilterStatus = { loading: false, error: null };
+
+    constructor(options: VideoFilterProcessorOptions) {
+        this.deps = { ...DEFAULT_DEPS, ...options.deps };
+        this.filters = options.filters;
+        this.backgroundImage = options.backgroundImage ?? null;
+        this.assetsUrl = options.assetsUrl;
+        this.onStatus = options.onStatus;
+        const frameRate = options.frameRate ?? DEFAULT_FRAME_RATE;
+        this.interval = 1000 / frameRate;
+
+        this.canvas = this.deps.createCanvas();
+        this.ctx = context2d(this.canvas);
+        this.track = this.canvas.captureStream(frameRate).getVideoTracks()[0];
+
+        this.video = this.deps.createVideo();
+        this.video.muted = true;
+        this.video.playsInline = true;
+        this.video.srcObject = new MediaStream([options.source]);
+        void this.video.play().catch(() => undefined);
+
+        this.syncModels();
+        this.publishStatus();
+        this.tick();
+    }
+
+    /** Changes the filters (and the background picture) without interrupting the video. Also retries a model that failed
+     * to load, so choosing a filter again is a retry. */
+    update(filters: VideoFilters, backgroundImage: BackgroundPicture | null): void {
+        this.filters = filters;
+        this.backgroundImage = backgroundImage;
+        this.syncModels(true);
+        this.publishStatus();
+    }
+
+    stop(): void {
+        this.stopped = true;
+        clearTimeout(this.timer);
+        this.video.pause();
+        this.video.srcObject = null;
+        this.track.stop();
+    }
+
+    private syncModels(retry = false): void {
+        if (needsSegmentation(this.filters) && (this.segmenterState === "idle" || (retry && this.segmenterState === "failed"))) {
+            this.segmenterState = "loading";
+            this.deps.createSegmenter(this.assetsUrl).then(
+                (segmenter) => {
+                    this.segmenter = segmenter;
+                    this.segmenterState = "ready";
+                    this.publishStatus();
+                },
+                () => {
+                    this.segmenterState = "failed";
+                    this.publishStatus();
+                },
+            );
+        }
+        if (needsFace(this.filters) && (this.faceState === "idle" || (retry && this.faceState === "failed"))) {
+            this.faceState = "loading";
+            this.deps.createFaceTracker(this.assetsUrl).then(
+                (tracker) => {
+                    this.faceTracker = tracker;
+                    this.faceState = "ready";
+                    this.publishStatus();
+                },
+                () => {
+                    this.faceState = "failed";
+                    this.publishStatus();
+                },
+            );
+        }
+    }
+
+    private publishStatus(): void {
+        if (this.stopped) {
+            return;
+        }
+        const wantsSegmentation = needsSegmentation(this.filters);
+        const wantsFace = needsFace(this.filters);
+        let error: string | null = null;
+        if (wantsSegmentation && this.segmenterState === "failed") {
+            error = SEGMENTATION_ERROR;
+        } else if (wantsFace && this.faceState === "failed") {
+            error = FACE_ERROR;
+        } else if (this.renderFailed) {
+            error = RENDER_ERROR;
+        }
+        const loading = (wantsSegmentation && this.segmenterState === "loading") || (wantsFace && this.faceState === "loading");
+        if (loading !== this.status.loading || error !== this.status.error) {
+            this.status = { loading, error };
+            this.onStatus?.(this.status);
+        }
+    }
+
+    private tick = (): void => {
+        if (this.stopped) {
+            return;
+        }
+        const started = this.deps.now();
+        if (this.video.readyState >= 2 && this.video.videoWidth > 0) {
+            try {
+                this.render(started);
+                if (this.renderFailed) {
+                    // Drawing works again - a single bad frame doesn't leave the warning up.
+                    this.renderFailed = false;
+                    this.publishStatus();
+                }
+            } catch {
+                // A frame that can't be drawn is skipped; the loop carries on, and the participant is told.
+                if (!this.renderFailed) {
+                    this.renderFailed = true;
+                    this.publishStatus();
+                }
+            }
+        }
+        this.timer = setTimeout(this.tick, Math.max(0, this.interval - (this.deps.now() - started)));
+    };
+
+    /** A scratch canvas of the given size, kept between frames. */
+    private layer(name: string, width: number, height: number): Layer {
+        let layer = this.layers.get(name);
+        if (!layer) {
+            const canvas = this.deps.createCanvas();
+            layer = { canvas, ctx: context2d(canvas) };
+            this.layers.set(name, layer);
+        }
+        if (layer.canvas.width !== width || layer.canvas.height !== height) {
+            layer.canvas.width = width;
+            layer.canvas.height = height;
+        }
+        return layer;
+    }
+
+    private render(now: number): void {
+        const { video, canvas, ctx, filters } = this;
+        const width = video.videoWidth;
+        const height = video.videoHeight;
+        if (canvas.width !== width || canvas.height !== height) {
+            canvas.width = width;
+            canvas.height = height;
+        }
+
+        if (filters.background === "none") {
+            ctx.drawImage(video, 0, 0, width, height);
+        } else {
+            this.drawBackground(now, width, height);
+        }
+        this.applyEffect(width, height);
+        if (filters.accessory !== "none") {
+            this.paintAccessory(filters.accessory, now, width, height);
+        }
+    }
+
+    /** The background, then - once the segmentation model is ready - the participant on top of it. */
+    private drawBackground(now: number, width: number, height: number): void {
+        const { video, ctx } = this;
+        const picture = this.backgroundImage;
+        if (this.filters.background === "image" && picture) {
+            const scale = Math.max(width / picture.width, height / picture.height);
+            const drawnWidth = picture.width * scale;
+            const drawnHeight = picture.height * scale;
+            ctx.drawImage(picture.source, (width - drawnWidth) / 2, (height - drawnHeight) / 2, drawnWidth, drawnHeight);
+        } else {
+            // Also the stand-in for a "custom image" background that has no image: blurred, never the real room.
+            const small = this.layer("blur", Math.ceil(width / BLUR_DIVISOR), Math.ceil(height / BLUR_DIVISOR));
+            small.ctx.imageSmoothingQuality = "high";
+            small.ctx.drawImage(video, 0, 0, small.canvas.width, small.canvas.height);
+            ctx.imageSmoothingQuality = "high";
+            ctx.drawImage(small.canvas, 0, 0, width, height);
+        }
+
+        const mask = this.segment(now);
+        if (!mask) {
+            return;
+        }
+        const maskLayer = this.layer("mask", mask.width, mask.height);
+        let image = this.maskImage;
+        if (!image || image.width !== mask.width || image.height !== mask.height) {
+            image = this.maskImage = maskLayer.ctx.createImageData(mask.width, mask.height);
+        }
+        maskToAlpha(mask.confidence, image.data);
+        maskLayer.ctx.putImageData(image, 0, 0);
+
+        const person = this.layer("person", width, height);
+        person.ctx.globalCompositeOperation = "source-over";
+        person.ctx.clearRect(0, 0, width, height);
+        person.ctx.drawImage(maskLayer.canvas, 0, 0, width, height);
+        person.ctx.globalCompositeOperation = "source-in";
+        person.ctx.drawImage(video, 0, 0, width, height);
+        person.ctx.globalCompositeOperation = "source-over";
+        ctx.drawImage(person.canvas, 0, 0);
+    }
+
+    private segment(now: number): PersonMask | null {
+        if (!this.segmenter) {
+            return null;
+        }
+        try {
+            return this.segmenter.segment(this.video, now);
+        } catch {
+            this.segmenter = null;
+            this.segmenterState = "failed";
+            this.publishStatus();
+            return null;
+        }
+    }
+
+    private applyEffect(width: number, height: number): void {
+        const { ctx } = this;
+        const effect = this.filters.effect;
+        if (effect === "pixelate") {
+            const small = this.layer("pixel", PIXEL_BLOCKS, Math.ceil((height / width) * PIXEL_BLOCKS));
+            small.ctx.drawImage(this.canvas, 0, 0, small.canvas.width, small.canvas.height);
+            ctx.imageSmoothingEnabled = false;
+            ctx.drawImage(small.canvas, 0, 0, width, height);
+            ctx.imageSmoothingEnabled = true;
+        } else if (effect !== "none") {
+            const pixels = ctx.getImageData(0, 0, width, height);
+            PIXEL_EFFECTS[effect](pixels.data);
+            ctx.putImageData(pixels, 0, 0);
+        }
+    }
+
+    private paintAccessory(accessory: Exclude<Accessory, "none">, now: number, width: number, height: number): void {
+        const face = this.trackFace(now);
+        const geometry: FaceGeometry | null = face ? faceGeometry(face, width, height) : null;
+        if (geometry) {
+            drawAccessory(this.ctx, accessory, geometry);
+        }
+    }
+
+    /** The face's landmarks for this frame - the last known ones for a few frames after it is lost. */
+    private trackFace(now: number): FaceLandmark[] | null {
+        if (!this.faceTracker) {
+            return null;
+        }
+        let found: FaceLandmark[] | null = null;
+        try {
+            found = this.faceTracker.detect(this.video, now);
+        } catch {
+            this.faceTracker = null;
+            this.faceState = "failed";
+            this.publishStatus();
+            return null;
+        }
+        if (found) {
+            this.lastFace = found;
+            this.framesWithoutFace = 0;
+        } else if (++this.framesWithoutFace > FACE_HOLD_FRAMES) {
+            this.lastFace = null;
+        }
+        return this.lastFace;
+    }
+}

package/apps/shared/media/filters/accessories.ts

@@ -0,0 +1,262 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The face accessories - sunglasses, cat ears, a party hat, a crown, a mustache - drawn as vector paths onto the
+ * filtered frame, so the plugin ships no image assets at all.
+ *
+ * Each one is drawn in the face's own coordinate frame: the origin sits on a landmark (between the eyes, the top of
+ * the forehead, the nose), the x axis runs along the line between the eyes so the accessory tilts with the head, and
+ * one unit is the distance between the outer corners of the eyes so it grows and shrinks with the head. That keeps
+ * every drawing routine below a few plain numbers in "face widths".
+ */
+import type { Accessory } from "./filterTypes.js";
+
+/** A landmark as the face model reports it: 0-1 across and down the frame. */
+export interface FaceLandmark {
+    x: number;
+    y: number;
+}
+
+export interface Point {
+    x: number;
+    y: number;
+}
+
+/** Where the parts of a face are, in canvas pixels. */
+export interface FaceGeometry {
+    /** Halfway between the outer corners of the eyes. */
+    eyes: Point;
+    /** The top of the forehead. */
+    forehead: Point;
+    noseTip: Point;
+    upperLip: Point;
+    /** The distance between the outer corners of the eyes - one unit of the accessories' coordinate frame. */
+    unit: number;
+    /** The tilt of the line between the eyes, in radians. */
+    angle: number;
+}
+
+// Indices into the 478-point face mesh (MediaPipe's canonical face model).
+const RIGHT_EYE_OUTER = 33;
+const LEFT_EYE_OUTER = 263;
+const FOREHEAD_TOP = 10;
+const NOSE_TIP = 1;
+const UPPER_LIP = 0;
+const MESH_POINTS = 468;
+
+/** Works out where the parts of a face are, in pixels, from the face mesh's landmarks - `null` when there are not
+ * enough of them to be a face mesh at all. */
+export function faceGeometry(landmarks: FaceLandmark[], width: number, height: number): FaceGeometry | null {
+    if (landmarks.length < MESH_POINTS) {
+        return null;
+    }
+    const at = (index: number): Point => ({ x: landmarks[index].x * width, y: landmarks[index].y * height });
+    const right = at(RIGHT_EYE_OUTER);
+    const left = at(LEFT_EYE_OUTER);
+    return {
+        eyes: { x: (right.x + left.x) / 2, y: (right.y + left.y) / 2 },
+        forehead: at(FOREHEAD_TOP),
+        noseTip: at(NOSE_TIP),
+        upperLip: at(UPPER_LIP),
+        unit: Math.hypot(left.x - right.x, left.y - right.y),
+        angle: Math.atan2(left.y - right.y, left.x - right.x),
+    };
+}
+
+/** Runs `draw` with the canvas moved to `origin`, turned by the face's tilt and scaled to one face width per unit. */
+function inFaceFrame(ctx: CanvasRenderingContext2D, origin: Point, face: FaceGeometry, draw: () => void): void {
+    ctx.save();
+    ctx.translate(origin.x, origin.y);
+    ctx.rotate(face.angle);
+    ctx.scale(face.unit, face.unit);
+    draw();
+    ctx.restore();
+}
+
+/** Runs `draw` once as it is and once flipped left-right, for the two matching halves of a symmetrical accessory. */
+function bothSides(ctx: CanvasRenderingContext2D, draw: () => void): void {
+    for (const side of [1, -1]) {
+        ctx.save();
+        ctx.scale(side, 1);
+        draw();
+        ctx.restore();
+    }
+}
+
+function roundedRect(ctx: CanvasRenderingContext2D, x: number, y: number, w: number, h: number, r: number): void {
+    ctx.beginPath();
+    ctx.moveTo(x + r, y);
+    ctx.arcTo(x + w, y, x + w, y + h, r);
+    ctx.arcTo(x + w, y + h, x, y + h, r);
+    ctx.arcTo(x, y + h, x, y, r);
+    ctx.arcTo(x, y, x + w, y, r);
+    ctx.closePath();
+}
+
+function drawSunglasses(ctx: CanvasRenderingContext2D, face: FaceGeometry): void {
+    inFaceFrame(ctx, face.eyes, face, () => {
+        ctx.fillStyle = "rgba(12, 12, 18, 0.93)";
+        ctx.strokeStyle = "rgba(12, 12, 18, 0.93)";
+        ctx.lineCap = "round";
+        bothSides(ctx, () => {
+            roundedRect(ctx, 0.06, -0.17, 0.54, 0.38, 0.12);
+            ctx.fill();
+            // The arm that runs back over the ear.
+            ctx.lineWidth = 0.04;
+            ctx.beginPath();
+            ctx.moveTo(0.6, -0.06);
+            ctx.lineTo(0.8, -0.1);
+            ctx.stroke();
+            // A glint across the lens.
+            ctx.fillStyle = "rgba(255, 255, 255, 0.2)";
+            ctx.beginPath();
+            ctx.moveTo(0.14, -0.1);
+            ctx.lineTo(0.28, -0.1);
+            ctx.lineTo(0.16, 0.12);
+            ctx.lineTo(0.1, 0.12);
+            ctx.closePath();
+            ctx.fill();
+        });
+        // The bridge between the lenses.
+        ctx.lineWidth = 0.05;
+        ctx.beginPath();
+        ctx.moveTo(-0.08, -0.08);
+        ctx.lineTo(0.08, -0.08);
+        ctx.stroke();
+    });
+}
+
+function drawCat(ctx: CanvasRenderingContext2D, face: FaceGeometry): void {
+    inFaceFrame(ctx, face.forehead, face, () => {
+        bothSides(ctx, () => {
+            ctx.fillStyle = "#3b3b44";
+            ctx.beginPath();
+            ctx.moveTo(0.68, 0.14);
+            ctx.lineTo(0.12, 0);
+            ctx.lineTo(0.62, -0.55);
+            ctx.closePath();
+            ctx.fill();
+            ctx.fillStyle = "#f4a6b8";
+            ctx.beginPath();
+            ctx.moveTo(0.56, 0.06);
+            ctx.lineTo(0.22, 0);
+            ctx.lineTo(0.58, -0.33);
+            ctx.closePath();
+            ctx.fill();
+        });
+    });
+    inFaceFrame(ctx, face.noseTip, face, () => {
+        ctx.fillStyle = "#f06a8a";
+        ctx.beginPath();
+        ctx.moveTo(-0.09, -0.04);
+        ctx.lineTo(0.09, -0.04);
+        ctx.lineTo(0, 0.06);
+        ctx.closePath();
+        ctx.fill();
+        ctx.lineCap = "round";
+        bothSides(ctx, () => {
+            for (const tilt of [-1, 0, 1]) {
+                ctx.beginPath();
+                ctx.moveTo(0.3, 0.04 + tilt * 0.07);
+                ctx.lineTo(0.85, -0.02 + tilt * 0.15);
+                // A dark line under a white one, so the whiskers read against a light or a dark background.
+                ctx.strokeStyle = "rgba(0, 0, 0, 0.45)";
+                ctx.lineWidth = 0.035;
+                ctx.stroke();
+                ctx.strokeStyle = "#ffffff";
+                ctx.lineWidth = 0.018;
+                ctx.stroke();
+            }
+        });
+    });
+}
+
+function drawPartyHat(ctx: CanvasRenderingContext2D, face: FaceGeometry): void {
+    inFaceFrame(ctx, face.forehead, face, () => {
+        ctx.save();
+        ctx.beginPath();
+        ctx.moveTo(-0.42, 0.1);
+        ctx.lineTo(0.42, 0.1);
+        ctx.lineTo(0.04, -1.15);
+        ctx.closePath();
+        ctx.clip();
+        ctx.fillStyle = "#ff5fa2";
+        ctx.fillRect(-0.6, -1.3, 1.2, 1.5);
+        ctx.strokeStyle = "#ffd23f";
+        ctx.lineWidth = 0.09;
+        for (const y of [-0.12, -0.42, -0.72]) {
+            ctx.beginPath();
+            ctx.moveTo(-0.6, y + 0.2);
+            ctx.lineTo(0.6, y - 0.2);
+            ctx.stroke();
+        }
+        ctx.restore();
+        ctx.fillStyle = "#ffffff";
+        ctx.beginPath();
+        ctx.arc(0.04, -1.15, 0.09, 0, Math.PI * 2);
+        ctx.fill();
+    });
+}
+
+function drawCrown(ctx: CanvasRenderingContext2D, face: FaceGeometry): void {
+    inFaceFrame(ctx, face.forehead, face, () => {
+        ctx.beginPath();
+        ctx.moveTo(-0.5, 0.1);
+        ctx.lineTo(-0.5, -0.45);
+        ctx.lineTo(-0.25, -0.2);
+        ctx.lineTo(0, -0.55);
+        ctx.lineTo(0.25, -0.2);
+        ctx.lineTo(0.5, -0.45);
+        ctx.lineTo(0.5, 0.1);
+        ctx.closePath();
+        ctx.fillStyle = "#f5c518";
+        ctx.fill();
+        ctx.strokeStyle = "#b8860b";
+        ctx.lineWidth = 0.03;
+        ctx.lineJoin = "round";
+        ctx.stroke();
+        for (const [x, y, color] of [
+            [-0.5, -0.45, "#e63946"],
+            [0, -0.55, "#3a86ff"],
+            [0.5, -0.45, "#e63946"],
+            [0, -0.05, "#2a9d8f"],
+        ] as const) {
+            ctx.fillStyle = color;
+            ctx.beginPath();
+            ctx.arc(x, y, 0.05, 0, Math.PI * 2);
+            ctx.fill();
+        }
+    });
+}
+
+function drawMustache(ctx: CanvasRenderingContext2D, face: FaceGeometry): void {
+    const between: Point = { x: (face.noseTip.x + face.upperLip.x) / 2, y: (face.noseTip.y + face.upperLip.y) / 2 };
+    inFaceFrame(ctx, between, face, () => {
+        ctx.fillStyle = "#3a2618";
+        ctx.beginPath();
+        ctx.moveTo(0, -0.03);
+        ctx.bezierCurveTo(-0.12, -0.12, -0.32, -0.1, -0.42, 0.02);
+        ctx.bezierCurveTo(-0.46, 0.07, -0.4, 0.13, -0.34, 0.09);
+        ctx.bezierCurveTo(-0.26, 0.04, -0.12, 0.06, 0, 0.09);
+        ctx.bezierCurveTo(0.12, 0.06, 0.26, 0.04, 0.34, 0.09);
+        ctx.bezierCurveTo(0.4, 0.13, 0.46, 0.07, 0.42, 0.02);
+        ctx.bezierCurveTo(0.32, -0.1, 0.12, -0.12, 0, -0.03);
+        ctx.closePath();
+        ctx.fill();
+    });
+}
+
+const DRAWERS: Record<Exclude<Accessory, "none">, (ctx: CanvasRenderingContext2D, face: FaceGeometry) => void> = {
+    sunglasses: drawSunglasses,
+    "cat-ears": drawCat,
+    "party-hat": drawPartyHat,
+    crown: drawCrown,
+    mustache: drawMustache,
+};
+
+/** Draws `accessory` onto `ctx` for the face at `face`. */
+export function drawAccessory(ctx: CanvasRenderingContext2D, accessory: Exclude<Accessory, "none">, face: FaceGeometry): void {
+    DRAWERS[accessory](ctx, face);
+}