SoulCast Getting Started Guide

SoulCast is a local-first AI chat and roleplay app. Bring your own API key to talk with an assistant, or create character cards for immersive roleplay.

This guide follows the product flow: Setup → Basic configuration → AI chat → Roleplay → Sherpa-ONNX on-device speech. When you finish, you will have a working first-time setup and both kinds of conversation ready.

1. Setup

1.1 Open the app

1. Launch SoulCast.
2. A brief splash screen appears (icon and “SoulCast”) with status text: “Starting…”, “Entering the app…”, then “Ready”.
3. You land on the main chat screen automatically.

No sign-up or login is required. Chats, characters, and settings are stored on your device by default.

1.2 Learn the main UI

The app centers on the main chat screen. Use the left drawer for sessions and features:

Main chat
 ├─ Left drawer (menu)
 │   ├─ New chat
 │   ├─ Characters
 │   ├─ Files
 │   ├─ Recent sessions
 │   └─ Settings
 └─ Top bar “Session info”

An empty session shows: “What would you like to talk about? Start a new conversation below.”
The input placeholder is “Ask SoulCast”.

Important: You can explore the UI immediately, but you will not get AI replies until you finish the provider and model setup in the next section.

2. Basic configuration

Entry: open the drawer from the top-left on the home screen → Settings at the bottom.

2.1 Suggested general settings (optional)

In Settings, adjust as needed:

2.2 Required: configure an AI provider and model

Without an available model, sending a message prompts you to configure a provider or pick a model. Follow these steps.

Step A: Add a provider

1. Settings → Providers
2. Tap Add provider (or Import provider and paste JSON)
3. Fill in:
   • Provider name: e.g. OpenAI, DeepSeek, OpenRouter
   • Base URL: e.g. https://api.openai.com
   • API path: e.g. /v1
   • API Key: your key
   • Request protocol: Chat Completions or Responses (per provider support)
4. Save the provider

Step B: Add and enable a model

1. On the provider page, open the Models tab
2. Use Fetch models to pull the list, or Add model manually
3. Set input / output formats (for text chat, at least enable “Text”; enable “Image” when you need image generation)
4. Turn on Enable model and save

Step C: Select the model in chat

1. Return to the main chat screen
2. Tap the model button in the input area (it may say “Select model”)
3. Choose the model you just enabled

Basic AI capability is ready.

2.3 Common advanced settings (optional)

After the required setup, tune as needed:

Enable tools for a given chat from the Tools / MCP panels at the bottom of the chat screen; keep secrets in Settings.

3. Basic AI chat

Normal sessions use the app-level assistant persona (adjustable under Settings › Prompts). Good for Q&A, writing, tools, and everyday use.

3.1 Start a new conversation

Either:

• Type in the current empty session; or
• Open the drawer → New chat

Confirm a usable model is selected in the input area.

3.2 Send and control

1. Type in “Ask SoulCast”
2. Tap Send
3. During generation, tap Stop to interrupt

Useful extras:

• Voice input: download a speech model in Settings, set it as default, and grant microphone permission
• Type @ to open the plugin menu (e.g. Create image)
• Tools panel: toggle built-in agent tools (time, location, weather, map, image gen, depending on config)
• MCP panel: toggle connected remote tools

3.3 Manage sessions

Open the drawer and check Recent:

• Pin / unpin
• Rename
• View info
• Delete (also clears that session’s messages)

After the first meaningful exchange, the system may auto-title the session.

3.4 Session info

From the top bar, open Session info to view or edit:

• Basic: summary, session system prompt, session worldbook, clear chat
• Long-term memory: managed by category (relationships, world lore, plot, preferences, constraints, other)

“Clear chat” removes messages only; basic config and long-term memory stay.

3.5 Message actions

On assistant messages you can usually:

• Regenerate and switch among versions
• Continue after an interrupt
• Copy
• Play (requires a default TTS setup)

4. Roleplay chat

Roleplay is driven by character cards: name, persona, scene, greetings, and more are injected into the roleplay prompt. The chat screen can also use the character avatar as an immersive background.

4.1 Create a character

1. Drawer → Characters
2. Tap New character (or Import character card, JSON / PNG)
3. Fill in or generate details, then Save

Option 1: AI-assisted generation (recommended to start)

1. On the edit screen, use AI assist
2. Describe the idea in one or two sentences, e.g. “A tsundere fox shrine maiden living in an old temple”
3. Pick a text model → Generate
4. Review the filled fields, edit as needed, then save

Option 2: Fill in manually

Main sections and fields:

Avatars can come from the photo library, the file library, or AI generation from a prompt (requires an image-capable model).

Save the character before binding a worldbook. Worldbook entries can inject extra lore when keywords match in chat.

4.2 Start a character chat

1. In Characters, select a character or tap Start chat
2. If there are multiple greetings, choose a greeting in the bottom sheet
3. The app creates a new character session (title is usually the character name; each start creates a new session)
4. If a greeting is configured, an assistant opening message appears, then you continue on the main chat screen

Differences vs normal chat:

In roleplay sessions, deep-thinking display may appear as “inner monologue”. From session info you can Edit character, or review long-term memory and worldbook bindings for that session.

4.3 Make roleplay more immersive (advanced)

1. Settings › Worldbook: create lore libraries and keyword entries
2. Bind primary/extra worldbooks on the character page, or a session worldbook in session info
3. Adjust roleplay-related templates under Settings › Prompts as needed
4. Set a suitable memory write frequency so relationships and plot can accumulate automatically

5. Sherpa-ONNX on-device speech

SoulCast speech recognition (ASR) and speech synthesis (TTS) are powered by Sherpa-ONNX. Models run on-device and do not go through a cloud speech service. The app does not ship built-in download URLs—paste an official model archive URL yourself.

5.1 Capabilities and entry points

Current support:

• ASR: streaming Online Transducer (typically streaming zipformer / zipformer2 packages with encoder / decoder / joiner and tokens.txt)
• TTS: VITS, Matcha, Kokoro, Pocket, Supertonic

Not supported yet: offline non-streaming ASR, streaming CTC-only packages, and TTS packages outside the adapted families.

5.2 Install a model (common steps)

1. Open Settings › Speech models
2. Tap Add model
3. Choose type: Speech recognition (ASR) or Speech synthesis (TTS)
4. Paste the model archive download URL (.tar.bz2 / .zip)
5. Optionally set a display name → Add
6. Tap Download in the list and wait until status goes from “Extracting…” to Ready
7. Tap Set as default for that model (ASR and TTS each need their own default)

With a default ASR ready, voice input works; with a default TTS ready, message playback works.

5.3 Speech output settings (TTS)

Settings › Speech output:

For non-Pocket models, choosing a speaker and speed is usually enough.

5.4 Recommended models

These URLs come from official Sherpa-ONNX releases and can be pasted into “Download URL”. Full lists:

• ASR: asr-models
• TTS: tts-models
• Docs: Pre-trained models

ASR (voice input) — prefer streaming Zipformer Transducer

Beginner default: install zh-int8-2025-06-30 first and set it as the default ASR.

Do not pick packages with ctc in the name, or non-streaming offline packages—the app expects streaming Transducer layouts, so those will not work for voice input.

TTS (message read-aloud) — prefer Chinese VITS

Beginner default: install vits-icefall-zh-aishell3, set it as the default TTS, then try a few speaker sids under Speech output.

For character-style voices, try official character packages (e.g. vits-zh-hf-keqing, vits-zh-hf-eula) from the same tts-models release.

5.5 Quick check

1. ASR: on the chat screen tap Voice input → grant microphone → speak Chinese → text appears in the input → Send
2. TTS: tap Play on an assistant message → you hear read-aloud; adjust speaker and speed under Speech output

5.6 Notes

• Model files are large; prefer Wi‑Fi. Keep the app in the foreground while downloading and extracting.
• ASR and TTS defaults are independent—set each as default separately.
• Pocket TTS cannot synthesize without a reference audio; pick a package sample or import a .wav under Speech output › Reference audio.
• Some packages such as vits-melo-tts-* may ship a problematic model.int8.onnx and fail on certain devices; for Chinese, prefer the icefall / aishell3 recommendations above.
• On-device model storage can be viewed and cleaned under Settings › Storage.

6. FAQ

7. Recommended first path (~10 minutes)

1. Open the app and enter the main screen
2. Settings › Providers: fill Base URL and API Key, add and enable at least one text model
3. Select the model on the main chat screen, send “Hello”, confirm normal chat works
4. Characters › New character: use AI assist to create and save a character
5. Start chat, pick a greeting, continue in roleplay

After that, explore worldbooks, long-term memory, tools, and speech when you need them. For voice input / read-aloud, see chapter 5.