rayenfeng/riko_project

The public version of the Riko Project

What it solves

Many AI companions feel static or require cloud services, and customizing them is hard. Riko provides a compact, open-source foundation (under 500 lines) where the entire personality, voice, and appearance are controlled from a single config file. It turns a standard chat script into a physical presence: you talk aloud, she answers aloud, and her 3D avatar moves her lips in sync, all on your own PC.

How it works

The core loop is: you press Enter to start recording, speak, press Enter to stop. Speech is converted to text using Faster-Whisper locally or Groq's online Whisper. That transcript goes to OpenAI GPT (any model, default gpt-4.1-mini) which generates a reply. The reply is turned into a voice clip using either GPT-SoVITS (local voice cloning) or Fish Audio (cloud voice). Finally, a VRM avatar displayed in your browser plays the clip and lip-syncs using three.js and three-vrm. Each step sits in its own file (asr.py, llm.py, tts.py, viewer.py), and main.py runs the sequence in a loop. The conversation history is stored in chat_history.json so she remembers.

Who it's for

This open-source snapshot is aimed at builders and tinkerers who want a clean, readable base to customize for their own AI companion. It requires some comfort with a terminal (uv and Python), plus API keys for OpenAI (and optionally Fish Audio or Groq). It runs on Windows 10/11 or Linux with Python 3.11+. If you prefer a no-code experience or want the latest features, the README points to paid options (Full Source on Patreon or a Desktop App).

Highlights

  • Push-to-talk voice input: press Enter, speak, press Enter.
  • Speech-to-text with local Faster-Whisper or cloud Groq.
  • Replies powered by OpenAI GPT with any model you choose.
  • Voice from GPT-SoVITS (local voice cloning) or Fish Audio (cloud).
  • A VRM avatar in your browser with lip sync; drag to rotate, right-drag to move, scroll to zoom.
  • All personality, avatar, and voice settings in one YAML file (character_config.yaml).
  • A setup checker that reports missing keys, servers, or files.
  • Total codebase under 500 lines, MIT licensed.
  • Chat history saved to a file you control.

Related

  • Project
    bishwaghimire/ai-learning-roadmaps

    A structured, all-in-one repository of learning roadmaps, books, courses, papers, tools, and communities for mastering AI/ML/DL — with separate paths for different career goals and skill levels.

  • Project
    ciddwd/overlay-translator

    An Android screen translation tool that overlays translated text on games, manga, and videos, supporting both offline and cloud-based OCR and translation engines.

  • Project
    rockbenben/subtitle-translator

    A browser-based and CLI tool for batch-translating subtitle files that preserves original timing and formatting by separating dialogue from technical metadata.

  • Project
    volcengine/SearchCLI

    SearchCLI is a command-line tool for managing and integrating Volcengine's AI search, recommendation, and conversational retrieval services into business applications and agent workflows.