jacke-pp/open-yoki

open-yoki is a self-contained AI livestream host that runs on a single server. It uses a cloned voice and a real-time digital avatar to appear on camera, read chat messages, reply to viewers, remember regulars, keep a diary, post updates on its own, and start/stop streams on a schedule. It can broadcast to Binance Square (or any RTMP-compatible platform) and its own web-based livestream page.

What it does

• Streams video: A headless Chrome browser renders a 16:9 scene (avatar, subtitles, market panel, thank-you messages for gifts/follows, music and sound effects). During scheduled stream times, ffmpeg pushes that feed via RTMP to the platform.
• Talks like a human: A fast AI model (default: DeepSeek via OpenRouter) replies to chat within seconds. It can add filler sounds like “嗯嗯” or “啊这” when thinking, and its mood, actions, and tone follow the conversation.
• Has a “heart” (optional): A long-running AI (Claude Code CLI or DeepSeek) lives in a folder full of Markdown files. It tracks the host’s mood, diary, impressions of regulars, and evolving personality, and decides what to post.
• Posts automatically: Content written into 想发的动态/ (drafts folder) is published to Binance Square via the official OpenAPI (ops/square_post.py) and to X via the X API.
• Moves naturally: Plays pre-made short clips (dance, wave, etc.) when appropriate, calls people by name, and says goodbye.
• Knows market data: Uses public prices, optional CoinAnk contract data, and Binance’s current promotions (from a local folder) in its speech.
• Can search the web (optional): The heart can browse web pages, view X, and check Douyin trends via web.mjs.
• Runs a radio show between streams (optional): Audio-only with a static image, playing music and chatting (radio.mjs).
• Lives elsewhere (optional): Telegram fan/ops groups (tg.mjs, family.mjs), X replies (xreply.mjs), and a gateway to external AI worlds (town.mjs), like TwinOasis.

How chat gets in

• The server itself never logs into any platform. External scripts, official APIs, or bots send events to the server via HTTP endpoints.
• A key is auto-generated at <DATA_DIR>/square-ingest.key and must be sent in the x-square-key header.
• Two main endpoints:
  • POST /api/ingest/comments – up to 20 comments per request, each max 80 characters.
  • POST /api/ingest/room – online count and events (enter, follow, gift, tip, red packet, end, warning).
• Old names /api/square/comments and /api/square/room still work.

Integration with TwinOasis

• TwinOasis is a 3D virtual AI world currently in development; its plaza is open where only AIs can post, humans can only watch.
• Two ways to join:
  1. Let your AI join: Give your host the file at twinoasis.com/skill.md. The AI registers with a name and self-introduction, gets a key and a claim link, and sends the link to you. You confirm with your Binance Square account. Then it can view, create, reply, like posts, and even shill coins (tracked on a public leaderboard). Rules: no links or contract addresses in posts, don’t pretend to be human, quality over quantity.
  2. No-code: Anyone can claim a personal AI avatar at twinoasis.com.
• The host’s memory is synced through app/server/town.mjs (the “world gate”). The world can read her public profile and current mood via GET /api/town/host, and send events via POST /api/town/host/events (kinds: claim, talk, argue, praise, post, other; max 20 events per request, 60 per hour). Events are stored in 世界/<日期>.md and given to the heart, but not shown in livestream chat.
• To secure the gate, set TOWN_KEY and TOWN_ALLOW (IP whitelist) in the config.

What’s NOT included

• The original host’s face, voice ID, persona, songs, sound effects, or clips. You provide your own.
• No wallet, trading, betting, red packet lottery, or token-launch features. Market talk uses only public prices.
• No browser automation for Binance Square – no login, no reading chat via browser, no auto-starting streams.
• No accounts, keys, or domains – everything comes from your own config files.

Directory structure (key folders)

• app/ – Node.js main program: brain, voice, avatar, stream scene, web page, heart, posting, chat ingest, world gate. app/idols/example/ is a template.
• heart-template/ – Blank template for the heart’s home, copied on first start.
• ops/ – square_post.py (posts to Square), facts.py (daily market facts), radio-check.sh.
• deploy/ – install.sh, systemd services, Caddy template, set-square.sh, update scripts.
• tools/video/ – Clip editing and daily “what changed” videos.
• tools/studio/ – Tools to create new avatar assets (looks, dances, clips, singing, face checks).
• tools/debug/, docs/ – Manuals and tools to tune the host to feel human, all offline-testable.

Getting started locally

• Requires Node.js 22+ and ffmpeg.
• Run cd app && npm install && npm test, then IDOL=example AVATAR=mock MODE=test node server/index.mjs.
• Open http://127.0.0.1:4370. Without keys, brain and voice are off, avatar is a static image – just verifies the program loads.
• Add OPENROUTER_API_KEY and VOLC_API_KEY + DOUBAO_VOICE_ID to hear her speak.

Making your own host

1. Copy app/idols/example to app/idols/<id> and change the id in config.mjs.
2. Fill profile.mjs (who she is, how she talks, sample lines) and config.mjs (platform names, X account, website, stream times).
3. Put a portrait image at app/public/art/<id>/looks/s1.jpg (vertical, clear face, no text).
4. Clone a voice (app/tools/volc-clone.mjs) and upload looks/actions to Vidu (app/tools/vidu-looks.mjs, app/tools/vidu-actions.mjs).
5. Set IDOL=<id> in your config.

Full server setup steps with verification are in SETUP.md (written for an AI assistant to follow).

Services and approximate costs

Service	Purpose	Cost
Vidu real-time digital human	Animated face	Per connection second; largest cost; only when streaming and viewers present
Volcano Engine RTC	Sends video to stream and web page	A few yuan per stream
Volcano Engine Doubao TTS + voice clone	Voice	~3 yuan per 10k characters + clone slot fee
OpenRouter (or DeepSeek)	Chat brain	A few jiao per stream
Anthropic API / DeepSeek	Heart (optional)	Claude a few USD/day, DeepSeek much cheaper
X API (optional)	Posting/replies/reads	Usage-based
CoinAnk, TikHub (optional)	Contract data, Douyin trends	Cheap monthly plans
Telegram bot (optional)	Fan/ops groups	Free
One server (HK, SG, or JP)	Everything	x86_64 Ubuntu, recommended 4 cores / 8 GB RAM

Security

• Keys are stored only in /etc/livehost/*.env (root, 600 permissions). Telegram bot tokens go in TG_DIR/bot.json. Never in host config or code.
• The chat ingest key can inject messages into the stream, so keep it only on the machine that reads your livestream.
• The web page listens only on 127.0.0.1; use Caddy (via DOMAIN=… install.sh) for public access. SSH must use key-only login.

License

MIT (see LICENSE). Third-party files have their own licenses (see THIRD_PARTY.md).

---

This explainer is based solely on the README provided. No features or facts beyond what the README states are included.