# tomari-guruguru: a browser avatar that turns 25 ways and talks with audio

> A Vite and React avatar for the character Tomari, shipped as two separate pages: one that follows the mouse across 25 pre-drawn directions, one that opens its mouth to microphone or audio file input. The code is MIT, the character art is not, and making it your own character is an image generation job rather than a coding job.

**rotejin/tomari-guruguru** — 25方向のマウス追従と口パクに対応したトマリ用ブラウザアバター

- Repository: https://github.com/rotejin/tomari-guruguru
- Website: https://rotejin.github.io/tomari-guruguru/
- Stars: 341 · Forks: 49
- Language: JavaScript
- License: MIT
- Published: 2026-09-18 · Updated: 2026-09-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/rotejin-tomari-guruguru

## guruguru.html follows the mouse, talk.html follows the audio

The repository ships two single page avatars for the same character instead of one app with a mode switch. guruguru.html is the mouse-following version: move the pointer and the character turns toward it, with automatic blinking layered on top. talk.html is the lip sync version: press the microphone start button, or load an audio file, and the mouth changes with the input level. index.html exists only to redirect visitors to talk.html, which is also the page the dev server opens for you. The install is a single command, and everything runs on the Vite dev server:

```bash
npm install
npm run dev
```

On Windows, start.bat starts the local server and opens the browser for you. Reaching the pages by hand during development means two addresses on port 5173, one per avatar.

## 25 directions are a 5 by 5 grid of c0 to c4 and r0 to r4

Direction is a lookup table of pre-drawn frames, nothing computed at runtime. Five columns cover left to right: c0 faces left, c1 is the left diagonal, c2 is straight ahead, c3 is the right diagonal, c4 faces right. Five rows cover up to down: r0 looks up strongly, r1 slightly up, r2 level, r3 slightly down, r4 strongly down. That gives 25 frames, and the app swaps a single image at a time out of public/slices2/ depending on the character's facing and expression. Those slices are tracked in git, which is why the repository carries image assets rather than generating them during the build. The lookup is centralized in src/character-config.js, where basePath and ext are the two values you change to point the avatar at a different set of slices, so swapping the art does not mean editing the app code.

## Six folders pair open and closed eyes with three mouth shapes

Expression is a second axis stacked on direction, encoded as six folders named A through F. A is open eyes with a closed mouth, B is open eyes with a mouth halfway, C is open eyes with a mouth fully open. D, E and F repeat those same three mouth shapes with the eyes closed, and that pairing is what lets the character blink while it talks: during speech, blinking switches to the D, E and F images, so the mouth keeps moving instead of freezing. A frame path therefore names both axes at once, for example slices2/A/r2c2.webp, which is eyes open, mouth closed, facing level and straight ahead. The three mouth shapes are exactly what the talk version selects between as volume rises, described as closed, half open and fully open. Direction times expression is the full frame set a custom character has to supply, and it arrives as six sheets rather than loose files.

## Microphone input needs localhost or HTTPS, and the fonts need a CDN

Two runtime constraints are stated outright under local startup. Microphone input is available only on localhost or over HTTPS, so opening the built page from a phone sitting on the same wifi, or from a plain http:// address on your own server, leaves you with no microphone input at all. The second is quieter: Google Fonts loads from a CDN, so the first display of the avatar needs a network connection even though the drawing and the audio handling happen in the browser. Neither is presented as a defect, both are notes in the setup section. The practical effect on testing is that npm run preview on 127.0.0.1 is the only local arrangement described as microphone capable, and the published GitHub Pages URL inherits whatever scheme the pages domain serves.

## preview starts on the GitHub Pages base path, not the dev path

The preview script exists to catch base path mistakes before deployment. The build produces the site, and the preview command serves it with the same /tomari-guruguru/ base path that GitHub Pages uses, which is why the preview addresses carry a prefix the dev server does not have:

```bash
npm run build
npm run preview   # ビルド結果をローカル確認
```

```text
http://127.0.0.1:4173/tomari-guruguru/talk.html
http://127.0.0.1:4173/tomari-guruguru/guruguru.html
```

The dev server serves the same two pages at 127.0.0.1:5173 with no prefix. package.json also defines verify:pages as node scripts/verify-pages-build.mjs, a check on the built output, and it pins Node in engines as ^20.19.0 || >=22.12.0, matching the Vite 8 requirement noted in the setup section.

## The program code is MIT, the character art is not

The licensing is split, and it is the first thing to read before reusing anything here. Program code is MIT. Character images, the sliced frames, thumbnails and audio files are explicitly outside MIT, and the permission granted is narrow: posting them on social networks for non-commercial use is fine, commercial use is prohibited, and reuse in other projects is prohibited. The terms sit in a separate ASSET_LICENSE.md at the top level rather than in LICENSE, so a skim of the repository badge tells you almost nothing about the art. The hosted demo at rotejin.github.io/tomari-guruguru/ therefore carries one author's character, and that art cannot move into a stream overlay, a client project or a monetised video without reading that file first. The advice to set the background color to something chroma key friendly points the intended use at a keyed overlay rather than a repackaged asset.

## Building a custom character is image generation plus a slicing script

Replacing the character is a five step pipeline, and none of the steps are code. Prepare a reference image of your own character, attach docs/01_画像生成用テンプレ.png to ChatGPT Images 2.0, follow the instructions in docs/01_画像生成用プロンプト.txt to produce the six sheets, drop the six PNG files into the 新キャラ資料/ folder, then run tools/slice_character_sheets.py to generate the sliced images. The docs/ directory exists to hold that material, with 01_画像指示例.png as a worked example, and the caveats plus the verification steps are collected in docs/新キャラ差し替え手順.md. The constraint worth noticing is that the prompt file and the slicing script assume one specific sheet layout, so a character drawn in some other arrangement will not slice cleanly without following the template.

## The Tweaks panel splits audio thresholds from follow behaviour

Live tuning happens in a panel at the bottom right of the page, opened from a Tweaks button, and the settings divide cleanly in two. The audio side covers microphone sensitivity, the lip sync threshold, how fast the mouth closes, and automatic blinking. The visual side covers follow range, follow speed, character size and background color. Threshold and closing speed decide whether speech reads as talking or as noise, and the mouth has only three shapes to work with, so those two values carry more weight than the rest. Follow range and follow speed are what keep the 25 direction grid from snapping around when the pointer moves fast. The stack behind it is deliberately small: Vite 8, React 18 and @vitejs/plugin-react 6, with react and react-dom as the only runtime dependencies in package.json.

## Conclusion

This suits a streamer who wants a keyed overlay for OBS and is willing to keep the shipped character. Three things decide it: microphone input only works on localhost or HTTPS, the character art cannot leave the repository commercially, and a custom character means generating six angle sheets with an image model and running a Python slicing script. Verify the asset terms in ASSET_LICENSE.md before any client work, and note that the repository publishes no releases and was last pushed on 2026-06-14, so there is no version history to pin against.

## FAQ

### What is tomari-guruguru and what are the two avatars it ships?

It is a browser avatar for the character Tomari, published on GitHub Pages. The guruguru version turns the character toward the mouse across 25 directions with automatic blinking, and the talk version switches the mouth between closed, half open and fully open from microphone or audio file input.

### Why does the microphone not work when I open tomari-guruguru from another device?

Microphone input is available only on localhost or over HTTPS, so a page opened from a phone on the same wifi has no microphone input. The setup notes also say Google Fonts loads from a CDN, so the first display needs a network connection.

### Can I use the tomari-guruguru character art in a commercial stream?

No. The program code is MIT licensed, but character images, sliced frames, thumbnails and audio files are outside MIT. Non-commercial posting on social networks is allowed, while commercial use and reuse in other projects are prohibited. The terms are in ASSET_LICENSE.md.

### How do I make tomari-guruguru use my own character?

The repository asks for six sheets of 25 directions. Attach docs/01_画像生成用テンプレ.png to ChatGPT Images 2.0, follow docs/01_画像生成用プロンプト.txt to generate the six sheets, place the PNG files in the 新キャラ資料/ folder, then run tools/slice_character_sheets.py. The slicing script assumes that one template layout.

## Sources

- [Issues](https://github.com/rotejin/tomari-guruguru/issues)
- [License: MIT](https://github.com/rotejin/tomari-guruguru/blob/main/LICENSE)
- [Project website](https://rotejin.github.io/tomari-guruguru/)
- [README](https://github.com/rotejin/tomari-guruguru/blob/main/README.md)
- [rotejin/tomari-guruguru on GitHub](https://github.com/rotejin/tomari-guruguru)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rotejin-tomari-guruguru