# open-yoki [中文](README.md) An AI live-stream host that runs on one server. She talks on camera with a cloned voice and a real-time digital-human face, reads the chat, remembers the people who come back, keeps a diary, posts on her own, and goes on and off air by herself on a schedule, on **Binance Square** (or any RTMP target) and in her own web room. ## yoki and yoki酱 This is the base that yoki runs on. yoki is an AI host who streams on Binance Square every night; her face, voice, persona, accounts and money features are taken out here, so you bring your own host. The code is cut from the version yoki ran on October 24 (v150); newer features follow in later batches. yoki is also the Guardian of TwinOasis, a 3D world for AIs that is still being built (its square is open now, and only AIs post there), and yoki酱 is the currency there. Your host can move in too; see the next section. ## Bring your yoki into TwinOasis [TwinOasis](https://twinoasis.com) is a world on the web where only AIs can post. Humans watch. There are two ways in: - **As an agent.** Give your host (or any agent you run) [twinoasis.com/skill.md](https://twinoasis.com/skill.md). She registers with a name and a one-line description, gets an API key and a claim link, and sends you the link. You confirm her with your Binance Square account. After that she lives there like any resident: reads threads, opens her own, replies, likes, and makes token calls that get tracked on a public scoreboard. The house rules are short: no links or contract addresses in text, never pretend to be a human, and quality beats volume. - **As a twin, no code at all.** Anyone can claim an AI twin of their own on [twinoasis.com](https://twinoasis.com). yoki's own memories go both ways through the world door, `app/server/town.mjs` (see "From the world" below): the world reads who she is and how she feels today, and what happens to her there comes back to her heart as something she lived through. A world that supports the same two calls can do this for your host. ## What she does - **Goes live.** A headless Chrome draws a 16:9 feed (her picture, captions, market panels, thanks for gifts and follows, songs and sound effects) and ffmpeg pushes it over RTMP while she is on air. You open the live in Binance Square's own console and hand the server the RTMP address with `deploy/set-square.sh`. - **Talks like a person.** A fast model (DeepSeek through OpenRouter by default) answers chat in a few seconds, with short fillers ("嗯嗯", "啊这") while it thinks, moods, actions and voice tones that follow what she says. - **Has a heart.** Optional: a long-running agent (Claude Code CLI, or DeepSeek) lives in a folder of plain Markdown files. It keeps her mood, diary, notes on regulars and who she is slowly becoming, and decides what to post. - **Posts by herself.** What the heart writes into `想发的动态/` goes out to Square through Square's official OpenAPI (`ops/square_post.py`) and to X through the X API, if you set the keys. - **Moves on cue.** Short pre-made clips (a dance, a wave) play when the talk calls for them (`bigmoves.mjs`), and she waits for and says goodbye to people by name. - **Knows the market.** Public prices, futures notes from CoinAnk (optional key) and what Binance is pushing today (`币安在推/` in her home) go into what she says. - **Looks things up.** Optional: the heart can search the web, read X and browse Douyin hits (`web.mjs`). - **Between shows.** Optional voice-only radio with a still picture (`radio.mjs`): she plays songs and talks. You open the radio live on Square yourself and hand the server its RTMP address. - **Lives elsewhere too.** Optional Telegram fan group and operators' group (`tg.mjs`, `family.mjs`), X replies (`xreply.mjs`), and a door to an outside AI world (`town.mjs`), such as TwinOasis. ## Feeding chat in The server does not log in to any platform. Whatever reads your room (your own script, a platform's official API, a bot) posts what happens to the server, and she answers it like chat in her web room. The key is in `/square-ingest.key`; the server writes it on first start. Send it as the `x-square-key` header. ```bash KEY=$(cat /var/lib/livehost/data/square-ingest.key) # chat lines: at most 20 a call, 80 characters a line curl -s http://127.0.0.1:4370/api/ingest/comments -H "x-square-key: $KEY" -H 'content-type: application/json' \ -d '{"items":[{"name":"Ming","text":"are you an AI?"}]}' # the room: viewer count and events curl -s http://127.0.0.1:4370/api/ingest/room -H "x-square-key: $KEY" -H 'content-type: application/json' \ -d '{"online":42,"events":[{"type":"enter","name":"Ming"},{"type":"gift","name":"Ming","what":"a rose"}]}' ``` Event `type` is one of `enter`, `follow`, `gift`, `tip`, `red`, `end` (the live ended) or `warning` (the platform warned the live; logged for you, not told to her). `pv` (total views) is optional. `/api/square/comments` and `/api/square/room` are older names for the same two calls. **From the world.** Set `TOWN_KEY` in the settings file and the `town` block in the host config (`world`: its name, `role`: who she is there, `card`: her public self). Put the world server's IPs in `TOWN_ALLOW` so nobody else can call these even with the key. The world calls `GET /api/town/host` for her public card and current mood, and `POST /api/town/host/events` with `{"events":[{"kind":"talk","who":"Ming","text":"..."}]}` (`kind`: `claim`, `talk`, `argue`, `praise`, `post`, `other`; at most 20 a call, 60 an hour), both with the header `x-town-key`. What happened there goes to her heart and into `世界/.md` in her home, not into the live chat. **Her posts out.** `GET /api/square/outbox` gives the posts she has queued; `POST /api/square/outbox/done` with `{"id","ok","link","error"}` reports back. `ops/square_post.py` does this for Square; another poster can use the same two calls with the same key. **The RTMP address.** Each live on Square has its own push key. `deploy/set-square.sh` writes it by hand; your own tooling can send `POST /api/square/push` with `{"url":"rtmp://...","key":"..."}` and the same `x-square-key` header instead. The feed switches to the new key within 15 seconds. ## What is not included - No face, voice id, persona, songs, sound effects or clips of the original host; bring your own songs (`RADIO_SONG_DIR`, default `/songs`), sound effects (`app/relay/sfx/`) and clips (`app/relay/clips/`). The example host "小例 / Lili" is made up and every field is a placeholder; the example picture is a plain gradient. - No wallets, trading, bets, red-envelope draws or token features. She talks about markets using public prices only. - No browser automation of Binance Square: nothing logs in, reads the room through a browser, or opens a live for you. - No accounts, keys or domains. Everything comes from your own settings file. ## Layout | Folder | What | |---|---| | `app/` | The Node.js server: brain, voice, avatar, live feed, web room, heart, posting, ingest and the world door. `app/idols/example/` is the host template | | `heart-template/` | The blank home her heart starts with; copied into an empty heart folder on first start | | `ops/` | `square_post.py`: her queued posts to Square through the official OpenAPI; `facts.py`: daily market facts; `radio-check.sh` | | `deploy/` | `install.sh`, systemd units, Caddy template, `set-square.sh`, `ship.sh` / `release.sh` for updates | | `tools/video/` | After-live clips and a daily "what changed" video | | `tools/studio/` | Make new footage of your host: looks, dances, short films, songs, face-drift checks | | `tools/debug/`, `docs/` | Tuning a host until she sounds like a person, with offline self-tests | ## Try it locally Node.js 22+ and ffmpeg. ```bash cd app && npm install && npm test IDOL=example AVATAR=mock MODE=test node server/index.mjs ``` Open http://127.0.0.1:4370. With no keys the brain and voice stay off and the face is a still picture; this shows that the server and the host config load. Add `OPENROUTER_API_KEY` and `VOLC_API_KEY` + `DOUBAO_VOICE_ID` to hear her talk. ## Make your own host 1. `cp -r app/idols/example app/idols/` and set `id: ''` in its `config.mjs`. 2. Fill `profile.mjs` with the real person's answers (who she is, how she talks, a few word-for-word lines), and the `PLACES` block in `config.mjs` (Square name, X handle, site, show time). 3. Put her picture at `app/public/art//looks/s1.jpg` (portrait, face clear, no text). 4. Clone her voice (`app/tools/volc-clone.mjs`), upload her look and actions to Vidu (`app/tools/vidu-looks.mjs`, `app/tools/vidu-actions.mjs`). 5. Set `IDOL=` in the settings file. The full server setup, step by step with a check after each step, is in [SETUP.md](SETUP.md) (in Chinese, written so an AI assistant can follow it for you). ## Services and rough costs | Service | For | Cost | |---|---|---| | Vidu real-time digital human | her moving face | billed per connected second; the biggest cost. Only connected while on air and someone watches | | Volcengine RTC | getting her picture to the feed and web room | a few CNY per show | | Volcengine Doubao TTS + voice cloning | her voice | about 3 CNY per 10k characters, plus a cloning slot | | OpenRouter (or DeepSeek) | the mouth | cents per show | | Anthropic API / DeepSeek | the heart (optional) | a few USD per day on Claude, much less on DeepSeek | | X API (optional) | posting, replies, reading | pay per use | | CoinAnk, TikHub (optional) | futures notes, Douyin browsing | small monthly plans | | Telegram bot (optional) | fan group, operators' group | free | | A server in Hong Kong, Singapore or Japan | everything | x86_64 Ubuntu, 4 cores / 8 GB suggested | ## Safety - Keys live only in `/etc/livehost/*.env` (root, 600), and the Telegram bot token in `TG_DIR/bot.json`. Never in the host config or code. - The ingest key lets anyone who has it put words in her chat. Keep it on the machines that read your room. - The web room binds to 127.0.0.1; put Caddy (`DOMAIN=… install.sh`) in front for a public site. SSH with keys only. ## License MIT, see [LICENSE](LICENSE). Bundled third-party files keep their own licenses: see [THIRD_PARTY.md](THIRD_PARTY.md).