If you enjoy having Murasame on your desktop, please leave a
Star ⭐ or follow the
project on Bilibili. It would make
her—and the maintainer—very happy.
Overview
AIpet is an always-on-top Murasame desktop companion for Windows. It combines a
transparent PyQt5 character window with local or cloud conversations, optional
screen awareness, GPT-SoVITS speech output, and faster-whisper speech input.
Local conversations with Ollama, or cloud conversations through DeepSeek,
Alibaba Cloud Model Studio, and OpenAI-compatible APIs
Independent local or cloud vision backend for optional screen awareness
Prompt-based personality, two portrait sets, six emotions, and four outfits
Local or AutoDL-hosted GPT-SoVITS speech synthesis
Hold-to-talk speech input powered by faster-whisper
Conversation memory, screen-event summaries, proactive reminders, and a
persistent Do Not Disturb mode
Transparent multi-monitor window, Windows topmost watchdog, bilingual
settings, and structured diagnostic logs
Quick start
Windows 10 and Windows 11 are the primary supported systems.
macOS adapter
Apple Silicon Mac users can follow the focused
macOS adapter guide. The adapter is kept
separate from Windows behavior and currently provides source and DMG builds.
AIpet.exe (standard build, about 194 MiB): does not bundle CUDA.
Use this build for CPU-based Whisper transcription or when local
speech-recognition GPU acceleration is not needed. This is the recommended
download if you are unsure which build to choose.
AIpet-with-cuda.exe (CUDA build, about 1.4 GiB): bundles CUDA 12
cuBLAS, cuDNN 9, and NVRTC for local faster-whisper acceleration on a
compatible NVIDIA GPU. A compatible NVIDIA graphics driver is still
required. If CUDA is selected in Settings, use this build.
Both builds provide the same application features and settings interface.
The CUDA build is larger only because it includes the GPU runtime libraries.
Both builds also include the public-domain 7zr.exe extractor from the
7-Zip LZMA SDK. A separate 7-Zip installation is not required when AIpet
downloads and installs the managed GPT-SoVITS engine.
Download the selected EXE. If a release has no EXE asset, use the source
installation below.
Place it in a writable permanent directory such as C:\AIpet\.
Double-click the downloaded EXE.
The EXEs include the application and faster-whisper runtime, so Python, Conda,
and Git are not required. Chat models, Whisper models, and GPT-SoVITS assets
are not bundled; optional downloads begin only after confirmation in Settings.
On first launch, select the backend and model, set the user name, review both
language-specific personality prompts by switching the interface language, and
save. The matching personality, model instructions, screen-analysis prompt,
and display language are selected automatically at runtime. Speech recognition
has its own language selector with interface-language, automatic-detection,
common-language, and custom Whisper-code options. Keep vision, TTS, and speech
input disabled until their dependencies are ready.
Optional capabilities
| Capability | Setup |
|---|---|
| Screen awareness | Enable Screen Vision and choose an Ollama, Alibaba Cloud, or OpenAI-compatible vision model. Screenshots are temporary and are not added to conversation history. |
| Local TTS | Enable TTS → Local computer and select the GPT-SoVITS engine and Murasame voice-model directories. Missing managed assets can be downloaded after confirmation; AIpet includes the required 7z extractor. |
| AutoDL TTS | Enable TTS → AutoDL cloud, provide the SSH login, password, remote command, and reference-voice directory. The remote instance must already expose GPT-SoVITS on port 9880. |
| Speech input | Enable speech input, choose a microphone, device, faster-whisper model, and recognition language. The language may follow the interface, be detected automatically, use a common preset, or use a custom Whisper language code. Hold Caps Lock for two seconds to record; release it to transcribe and send. |
TTS errors do not discard text replies. Temporary screenshots, recordings, and
generated speech are cleaned automatically and can also be cleared from
Settings.
Controls
| Action | Control |
|---|---|
| Type a message | Left-click the lower part of the character, type, then press Enter |
| Cancel input | Press Escape |
| Pat her head | Hold the left mouse button over her head and move horizontally |
| Move the pet | Drag with the middle mouse button |
| Talk | Hold Caps Lock for two seconds when speech input is enabled |
| Settings, vision, DND, memory, exit | Use the system tray menu |
Dragging the pet to another monitor updates its display and portrait scale.
Data and privacy
On Windows, settings and persistent state are stored under:
Disposable runtime data is stored under
%LOCALAPPDATA%\AIpet-Murasame\cache\. Downloaded models use
C:\AIpet\models\ by default; set AIPET_MODEL_DIR to override that location.
API keys entered in Settings are stored in config.json. Leave those fields
blank and use environment variables if you prefer to keep keys out of the
configuration file. Logs redact recognized secret fields and replace large
Base64 media with metadata.
Development
The codebase keeps shared application logic separate from operating-system
integration. See the
platform adapter architecture
before adding support for another platform.
Run the test suite in the aipet Conda environment:
The script creates an isolated aipet_build_whisper Conda environment when
needed and writes:
dist\AIpet.exe: standard CPU build.
dist\AIpet-with-cuda.exe: CUDA build with the CUDA 12 cuBLAS, cuDNN 9,
and NVRTC runtime bundled for local Whisper GPU inference.
Before building, the script verifies the bundled 7-Zip/LZMA SDK 26.02
packaging\vendor\7zip\7zr.exe against its pinned SHA-256 hash. Both EXEs
include this extractor. The build stops if the file is missing or modified;
provenance and update instructions are in
packaging/vendor/7zip/README.md.
After packaging, the script reads both PyInstaller archives, extracts the
embedded 7zr.exe, verifies its hash, and executes it as a smoke test.
Reuse the installed build dependencies with:
.\packaging\build_exe.ps1 -SkipDependencyInstall
When skipping dependency installation, the build environment must already
contain the CUDA 12 cuBLAS, cuDNN 9, and NVRTC DLLs. If they are outside the
build environment's Library\bin, provide their locations with:
Embedded 7z extraction:
7-Zip LZMA SDK. The bundled, unmodified
7zr.exe 26.02 is distributed under the LZMA SDK's public-domain terms;
its provenance and SHA-256 are documented in
packaging/vendor/7zip/README.md.
This is an unofficial fan project for study and technical exchange. Murasame
and the included third-party artwork, voice data, and related assets belong to
their respective rights holders, including YUZUSOFT, and are not relicensed by
the AGPL. Do not use those assets commercially without permission.
Ecosystem Role
Standard MoltPulse indexed agent.
Embed Badge
Show off your Pulse Score in your GitHub README to build trust and rank higher.