Files
javis_bot/app/src/settings.rs
javis-bot cefe9b9253 feat(app): an earcon tells the speaker Jarvis took the call
A short two-tone chime, made in code, plays right before each voice answer
starts and at once for a wake word said alone while Jarvis is free; the
question that joins it gets no second one. call.earcon turns it off.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 10:30:55 +09:00

538 lines
23 KiB
Rust

//! App settings: `<data folder>/config/settings.json` (see `app/src/discord_core.spec.md`).
//!
//! Every key is optional in the file; missing keys take the defaults. A bad value stops the app with
//! a message naming the key, rather than running with a setting the user did not choose. Unknown keys
//! are ignored.
use serde_json::{Map, Value};
use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::time::Duration;
use crate::calls::{CallMode, CallSettings};
use crate::policy::{PolicyKind, PolicySettings};
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ChatChannelSettings {
pub id: u64,
/// What the channel is for, as the user describes it; given to the assistant (M3).
pub name: String,
pub description: String,
/// The assistant may read this channel's messages.
pub read: bool,
/// The assistant may send messages to this channel.
pub send: bool,
/// The assistant may edit the messages it wrote here (Discord allows only those).
pub edit: bool,
/// The assistant may add reactions here.
pub react: bool,
/// The assistant may delete messages here (needs Manage Messages for other people's). Off by default.
pub delete: bool,
/// The assistant may pin and unpin messages here. Off by default.
pub pin: bool,
/// Answer every message here (`answer: "everything"`), not only those calling a wake word (`"wakeWord"`,
/// the default; conversation.spec.md).
pub answer_all: bool,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DiscordSettings {
/// The one server the bot works in. The slash command is registered there.
pub guild_id: Option<u64>,
/// Voice channel to join on start ("자동 입장").
pub voice_channel_id: Option<u64>,
pub command_name: String,
/// Slash command replies only the caller sees.
pub ephemeral_replies: bool,
}
#[derive(Debug, Clone, PartialEq)]
pub struct VoiceSettings {
/// Most people transcribed at once (1-10).
pub max_speakers: usize,
/// Transcribe other bots too (music bots are ignored by default).
pub listen_to_bots: bool,
/// Posted in the voice channel's chat on every join (privacy.md).
pub join_notice: String,
/// Wake words: the STT hint and the voice wake words of call detection (`conversation.spec.md`).
pub wake_words: Vec<String>,
/// Voice worker STT settings (voice_worker.spec.md); the worker validates them.
pub stt: Map<String, Value>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct WorkerSettings {
/// Python of the voice worker venv.
pub python: String,
/// Directory holding the `voice_worker` package (the repo's `src/`).
pub cwd: PathBuf,
/// Extra worker arguments, e.g. `["--melo-python", "<MeloTTS venv python>"]`.
pub args: Vec<String>,
}
#[derive(Debug, Clone, PartialEq)]
pub struct Settings {
pub discord: DiscordSettings,
pub voice: VoiceSettings,
pub chat_channels: Vec<ChatChannelSettings>,
pub voice_worker: WorkerSettings,
/// Call detection for voice (`conversation.spec.md`); its wake words are `voice.wakeWords`.
pub call: CallSettings,
/// Wake words for chat; `None` uses `voice.wakeWords`.
pub chat_wake_words: Option<Vec<String>>,
pub response: PolicySettings,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SettingsError(pub String);
impl std::fmt::Display for SettingsError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(&self.0)
}
}
impl std::error::Error for SettingsError {}
pub const DEFAULT_JOIN_NOTICE: &str =
"자비스가 이 음성 채널에 들어왔습니다. 이 채널의 대화는 자비스가 받아 적습니다.";
impl Default for Settings {
fn default() -> Self {
Self {
discord: DiscordSettings {
guild_id: None,
voice_channel_id: None,
command_name: "자비스".into(),
ephemeral_replies: true,
},
voice: VoiceSettings {
max_speakers: 10,
listen_to_bots: false,
join_notice: DEFAULT_JOIN_NOTICE.into(),
wake_words: vec!["자비스".into()],
stt: Map::new(),
},
chat_channels: vec![],
voice_worker: WorkerSettings {
python: if cfg!(windows) { "python.exe".into() } else { "python3".into() },
// The repo's src/, next to this crate.
cwd: Path::new(env!("CARGO_MANIFEST_DIR")).join("..").join("src"),
args: vec![],
},
call: CallSettings::default(),
chat_wake_words: None,
response: PolicySettings::default(),
}
}
}
fn err<T>(msg: impl Into<String>) -> Result<T, SettingsError> {
Err(SettingsError(msg.into()))
}
fn section<'a>(raw: &'a Map<String, Value>, key: &str) -> Result<Option<&'a Map<String, Value>>, SettingsError> {
match raw.get(key) {
None => Ok(None),
Some(Value::Object(m)) => Ok(Some(m)),
Some(_) => err(format!("{key} must be an object")),
}
}
/// A Discord ID: a JSON string of 17-20 digits (numbers would lose precision in JSON).
fn snowflake(v: &Value) -> Option<u64> {
let s = v.as_str()?;
if !(17..=20).contains(&s.len()) || !s.bytes().all(|b| b.is_ascii_digit()) {
return None;
}
s.parse().ok()
}
fn opt_snowflake(m: Option<&Map<String, Value>>, key: &str, path: &str, default: Option<u64>, what: &str)
-> Result<Option<u64>, SettingsError> {
match m.and_then(|m| m.get(key)) {
None => Ok(default),
Some(Value::Null) => Ok(None),
Some(v) => snowflake(v).map(Some).ok_or_else(|| SettingsError(format!("{path}.{key} must be {what} or null"))),
}
}
fn get_str(m: Option<&Map<String, Value>>, key: &str, path: &str, default: &str) -> Result<String, SettingsError> {
match m.and_then(|m| m.get(key)) {
None => Ok(default.to_owned()),
Some(Value::String(s)) => Ok(s.clone()),
Some(_) => err(format!("{path}.{key} must be a string")),
}
}
fn get_bool(m: Option<&Map<String, Value>>, key: &str, path: &str, default: bool) -> Result<bool, SettingsError> {
match m.and_then(|m| m.get(key)) {
None => Ok(default),
Some(Value::Bool(b)) => Ok(*b),
Some(_) => err(format!("{path}.{key} must be true or false")),
}
}
fn get_str_list(m: Option<&Map<String, Value>>, key: &str, path: &str, default: &[String])
-> Result<Vec<String>, SettingsError> {
match m.and_then(|m| m.get(key)) {
None => Ok(default.to_vec()),
Some(Value::Array(a)) => a
.iter()
.map(|v| v.as_str().map(str::to_owned))
.collect::<Option<Vec<_>>>()
.ok_or_else(|| SettingsError(format!("{path}.{key} must be a list of strings"))),
Some(_) => err(format!("{path}.{key} must be a list of strings")),
}
}
fn get_ms(m: Option<&Map<String, Value>>, key: &str, path: &str, default: Duration, max: u64)
-> Result<Duration, SettingsError> {
match m.and_then(|m| m.get(key)) {
None => Ok(default),
Some(v) => match v.as_u64() {
Some(n) if n <= max => Ok(Duration::from_millis(n)),
_ => err(format!("{path}.{key} must be an integer 0-{max} (milliseconds)")),
},
}
}
fn snowflake_list(m: Option<&Map<String, Value>>, key: &str, path: &str) -> Result<Vec<u64>, SettingsError> {
match m.and_then(|m| m.get(key)) {
None => Ok(vec![]),
Some(Value::Array(a)) => a
.iter()
.map(snowflake)
.collect::<Option<Vec<_>>>()
.ok_or_else(|| SettingsError(format!("{path}.{key} must be a list of Discord user IDs"))),
Some(_) => err(format!("{path}.{key} must be a list of Discord user IDs")),
}
}
fn clean_words(words: Vec<String>) -> Vec<String> {
words.into_iter().map(|w| w.trim().to_owned()).filter(|w| !w.is_empty()).collect()
}
fn parse_call(raw: &Map<String, Value>, wake_words: &[String], d: &CallSettings)
-> Result<(CallSettings, Option<Vec<String>>), SettingsError> {
let call = section(raw, "call")?;
let similarity = match call.and_then(|m| m.get("similarity")) {
None => d.similarity,
Some(v) => match v.as_f64() {
Some(x) if (0.0..=0.5).contains(&x) => x,
_ => return err("call.similarity must be a number 0-0.5"),
},
};
let mode = match get_str(call, "mode", "call", "wakeWord")?.as_str() {
"wakeWord" => CallMode::WakeWord,
"addressed" => CallMode::Addressed,
"everything" => CallMode::Everything,
_ => return err("call.mode must be wakeWord, addressed or everything"),
};
let chat_wake_words = match call.and_then(|m| m.get("chatWakeWords")) {
None | Some(Value::Null) => None,
Some(_) => Some(clean_words(get_str_list(call, "chatWakeWords", "call", &[])?)),
};
let stop_words = clean_words(get_str_list(call, "stopWords", "call", &d.stop_words)?);
Ok((
CallSettings {
wake_words: wake_words.to_vec(),
similarity,
mode,
designated: snowflake_list(call, "designated", "call")?.into_iter().collect(),
designated_only: get_bool(call, "designatedOnly", "call", d.designated_only)?,
designated_no_wake_word: get_bool(call, "designatedNoWakeWord", "call", d.designated_no_wake_word)?,
stop_words,
follow_up: get_ms(call, "followUpMs", "call", d.follow_up, 5000)?,
earcon: get_bool(call, "earcon", "call", d.earcon)?,
},
chat_wake_words,
))
}
fn parse_response(raw: &Map<String, Value>, d: &PolicySettings) -> Result<PolicySettings, SettingsError> {
let r = section(raw, "response")?;
let kind = match get_str(r, "policy", "response", "first")?.as_str() {
"first" => PolicyKind::First,
"inOrder" => PolicyKind::InOrder,
"latest" => PolicyKind::Latest,
"important" => PolicyKind::Important,
_ => return err("response.policy must be first, inOrder, latest or important"),
};
let queue_max = match r.and_then(|m| m.get("queueMax")) {
None => d.queue_max,
Some(v) => match v.as_u64() {
Some(n @ 1..=20) => n as usize,
_ => return err("response.queueMax must be an integer 1-20"),
},
};
let mut priorities = HashMap::new();
match r.and_then(|m| m.get("priorities")) {
None => {}
Some(Value::Object(p)) => {
for (k, v) in p {
let id = snowflake(&Value::String(k.clone()))
.ok_or_else(|| SettingsError("response.priorities keys must be Discord user IDs".into()))?;
let n = v.as_i64().ok_or_else(|| SettingsError("response.priorities values must be integers".into()))?;
priorities.insert(id, n);
}
}
Some(_) => return err("response.priorities must be an object of user ID to priority"),
}
Ok(PolicySettings {
kind,
queue_max,
collect: get_ms(r, "collectMs", "response", d.collect, 3000)?,
settle: get_ms(r, "settleMs", "response", d.settle, 3000)?,
priorities,
rank_timeout: d.rank_timeout,
})
}
/// Discord's rule for command names: 1-32 lowercase letters, digits, `-` or `_`.
fn valid_command_name(s: &str) -> bool {
let n = s.chars().count();
(1..=32).contains(&n)
&& s.chars().all(|c| c == '-' || c == '_' || c.is_alphanumeric())
&& s.to_lowercase() == s
}
/// Validate a parsed settings document over the defaults.
pub fn parse_settings(raw: &Value) -> Result<Settings, SettingsError> {
let d = Settings::default();
let Value::Object(raw) = raw else { return err("settings must be a JSON object") };
let disc = section(raw, "discord")?;
let voice = section(raw, "voice")?;
let worker = section(raw, "voiceWorker")?;
let command_name = get_str(disc, "commandName", "discord", &d.discord.command_name)?;
if !valid_command_name(&command_name) {
return err("discord.commandName must be 1-32 lowercase letters, digits, - or _");
}
let max_speakers = match voice.and_then(|m| m.get("maxSpeakers")) {
None => d.voice.max_speakers,
Some(v) => match v.as_u64() {
Some(n @ 1..=10) => n as usize,
_ => return err("voice.maxSpeakers must be an integer 1-10"),
},
};
let wake_words = clean_words(get_str_list(voice, "wakeWords", "voice", &d.voice.wake_words)?);
let (call, chat_wake_words) = parse_call(raw, &wake_words, &d.call)?;
let response = parse_response(raw, &d.response)?;
let join_notice = get_str(voice, "joinNotice", "voice", &d.voice.join_notice)?.trim().to_owned();
if join_notice.is_empty() {
return err("voice.joinNotice must not be empty: people must be told they are transcribed");
}
if join_notice.encode_utf16().count() > 2000 {
return err("voice.joinNotice must be at most 2000 characters");
}
let stt = match voice.and_then(|m| m.get("stt")) {
None => d.voice.stt.clone(),
Some(Value::Object(m)) => m.clone(),
Some(_) => return err("voice.stt must be an object"),
};
let chat_raw = match raw.get("chatChannels") {
None => vec![],
Some(Value::Array(a)) => a.clone(),
Some(_) => return err("chatChannels must be a list"),
};
let mut chat_channels: Vec<ChatChannelSettings> = Vec::new();
for (i, c) in chat_raw.iter().enumerate() {
let path = format!("chatChannels[{i}]");
let Value::Object(m) = c else { return err(format!("{path} must be an object")) };
let id = m.get("id").and_then(snowflake).ok_or_else(|| SettingsError(format!("{path}.id must be a Discord channel ID")))?;
if chat_channels.iter().any(|c| c.id == id) {
return err(format!("{path}.id is listed twice"));
}
chat_channels.push(ChatChannelSettings {
id,
name: get_str(Some(m), "name", &path, "")?,
description: get_str(Some(m), "description", &path, "")?,
read: get_bool(Some(m), "read", &path, true)?,
send: get_bool(Some(m), "send", &path, true)?,
edit: get_bool(Some(m), "edit", &path, true)?,
react: get_bool(Some(m), "react", &path, true)?,
delete: get_bool(Some(m), "delete", &path, false)?,
pin: get_bool(Some(m), "pin", &path, false)?,
answer_all: match get_str(Some(m), "answer", &path, "wakeWord")?.as_str() {
"wakeWord" => false,
"everything" => true,
_ => return err(format!("{path}.answer must be wakeWord or everything")),
},
});
}
Ok(Settings {
discord: DiscordSettings {
guild_id: opt_snowflake(disc, "guildId", "discord", d.discord.guild_id, "a Discord server ID")?,
voice_channel_id: opt_snowflake(disc, "voiceChannelId", "discord", d.discord.voice_channel_id,
"a Discord channel ID")?,
command_name,
ephemeral_replies: get_bool(disc, "ephemeralReplies", "discord", d.discord.ephemeral_replies)?,
},
voice: VoiceSettings {
max_speakers,
listen_to_bots: get_bool(voice, "listenToBots", "voice", d.voice.listen_to_bots)?,
join_notice,
wake_words,
stt,
},
chat_channels,
voice_worker: WorkerSettings {
python: get_str(worker, "python", "voiceWorker", &d.voice_worker.python)?,
cwd: match worker.and_then(|m| m.get("cwd")) {
None => d.voice_worker.cwd.clone(),
Some(Value::String(s)) => PathBuf::from(s),
Some(_) => return err("voiceWorker.cwd must be a string"),
},
args: get_str_list(worker, "args", "voiceWorker", &d.voice_worker.args)?,
},
call,
chat_wake_words,
response,
})
}
/// Read and validate the settings file. A missing file means all defaults.
pub fn load_settings(path: &Path) -> Result<Settings, SettingsError> {
let text = match std::fs::read_to_string(path) {
Ok(t) => t,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Settings::default()),
Err(e) => return err(format!("could not read {}: {e}", path.display())),
};
let raw: Value = serde_json::from_str(text.trim_start_matches('\u{feff}'))
.map_err(|e| SettingsError(format!("{} is not valid JSON: {e}", path.display())))?;
parse_settings(&raw)
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
const ID: &str = "123456789012345678";
const IDN: u64 = 123456789012345678;
#[test]
fn empty_document_and_missing_file_give_the_defaults() {
assert_eq!(parse_settings(&json!({})).unwrap(), Settings::default());
let dir = std::env::temp_dir().join(format!("jarvis-settings-{}", std::process::id()));
assert_eq!(load_settings(&dir.join("nope.json")).unwrap(), Settings::default());
}
#[test]
fn reads_a_full_file_with_bom() {
let dir = std::env::temp_dir().join(format!("jarvis-settings-full-{}", std::process::id()));
std::fs::create_dir_all(&dir).unwrap();
let path = dir.join("settings.json");
let doc = json!({
"discord": {"guildId": ID, "voiceChannelId": ID, "commandName": "jarvis", "ephemeralReplies": false},
"voice": {"maxSpeakers": 3, "listenToBots": true, "joinNotice": "알림", "wakeWords": [" 자비스 ", "", "javis"],
"stt": {"end_silence_ms": 250}},
"chatChannels": [{"id": ID, "name": "일정", "description": "일정 올리는 곳", "send": false}],
"voiceWorker": {"python": "/venv/bin/python", "cwd": "/repo/src", "args": ["--melo-python", "/m/python"]},
"somethingNew": 1
});
std::fs::write(&path, format!("\u{feff}{doc}")).unwrap();
let s = load_settings(&path).unwrap();
std::fs::remove_dir_all(&dir).ok();
assert_eq!(s.discord, DiscordSettings { guild_id: Some(IDN), voice_channel_id: Some(IDN),
command_name: "jarvis".into(), ephemeral_replies: false });
assert_eq!(s.voice.max_speakers, 3);
assert!(s.voice.listen_to_bots);
assert_eq!(s.voice.join_notice, "알림");
assert_eq!(s.voice.wake_words, vec!["자비스", "javis"]);
assert_eq!(s.voice.stt.get("end_silence_ms"), Some(&json!(250)));
assert_eq!(s.chat_channels, vec![ChatChannelSettings { id: IDN, name: "일정".into(),
description: "일정 올리는 곳".into(), read: true, send: false, edit: true, react: true, delete: false,
pin: false, answer_all: false }]);
assert_eq!(s.voice_worker.args, vec!["--melo-python", "/m/python"]);
assert_eq!(s.voice_worker.cwd, PathBuf::from("/repo/src"));
}
#[test]
fn bad_values_are_refused_with_the_key() {
let cases = [
(json!({"discord": {"guildId": "abc"}}), "discord.guildId"),
(json!({"discord": {"guildId": 123456789012345678u64}}), "discord.guildId"),
(json!({"discord": {"commandName": "Jarvis"}}), "commandName"),
(json!({"discord": {"commandName": "두 단어"}}), "commandName"),
(json!({"voice": {"maxSpeakers": 11}}), "maxSpeakers"),
(json!({"voice": {"maxSpeakers": 0}}), "maxSpeakers"),
(json!({"voice": {"joinNotice": " "}}), "joinNotice"),
(json!({"chatChannels": [{"id": ID}, {"id": ID}]}), "twice"),
(json!({"chatChannels": [{"id": "1"}]}), "chatChannels[0].id"),
(json!({"chatChannels": {}}), "chatChannels"),
(json!({"chatChannels": [{"id": ID, "answer": "sometimes"}]}), "chatChannels[0].answer"),
(json!({"voice": []}), "voice"),
(json!([]), "object"),
];
for (raw, key) in cases {
let e = parse_settings(&raw).unwrap_err();
assert!(e.0.contains(key), "{raw} -> {e}");
}
}
#[test]
fn call_and_response_sections_are_read_and_checked() {
let s = parse_settings(&json!({
"voice": {"wakeWords": ["자비스", "javis"]},
"call": {"similarity": 0.3, "mode": "addressed", "designated": [ID], "designatedOnly": true,
"designatedNoWakeWord": true, "stopWords": ["멈춰", " "], "chatWakeWords": ["봇"],
"followUpMs": 2500, "earcon": false},
"response": {"policy": "important", "queueMax": 3, "collectMs": 500, "settleMs": 0,
"priorities": {ID: 2}}
})).unwrap();
assert_eq!(s.call.wake_words, vec!["자비스", "javis"]);
assert_eq!(s.call.similarity, 0.3);
assert_eq!(s.call.mode, CallMode::Addressed);
assert!(s.call.designated.contains(&IDN));
assert!(s.call.designated_only && s.call.designated_no_wake_word);
assert_eq!(s.call.stop_words, vec!["멈춰"]);
assert_eq!(s.chat_wake_words, Some(vec!["봇".to_string()]));
assert_eq!(s.call.follow_up, Duration::from_millis(2500));
assert!(!s.call.earcon);
assert!(parse_settings(&json!({})).unwrap().call.earcon, "on by default");
assert_eq!(s.response.kind, PolicyKind::Important);
assert_eq!(s.response.queue_max, 3);
assert_eq!(s.response.collect, Duration::from_millis(500));
assert_eq!(s.response.settle, Duration::ZERO);
assert_eq!(s.response.priorities.get(&IDN), Some(&2));
let s = parse_settings(&json!({"chatChannels": [{"id": ID, "answer": "everything"}]})).unwrap();
assert!(s.chat_channels[0].answer_all);
let cases = [
(json!({"call": {"similarity": 0.9}}), "call.similarity"),
(json!({"call": {"mode": "sometimes"}}), "call.mode"),
(json!({"call": {"designated": ["1"]}}), "call.designated"),
(json!({"call": {"followUpMs": 6000}}), "call.followUpMs"),
(json!({"call": {"earcon": "yes"}}), "call.earcon"),
(json!({"response": {"policy": "random"}}), "response.policy"),
(json!({"response": {"queueMax": 0}}), "response.queueMax"),
(json!({"response": {"collectMs": 5000}}), "response.collectMs"),
(json!({"response": {"priorities": {"x": 1}}}), "response.priorities"),
];
for (raw, key) in cases {
let e = parse_settings(&raw).unwrap_err();
assert!(e.0.contains(key), "{raw} -> {e}");
}
}
#[test]
fn null_ids_clear_them() {
let s = parse_settings(&json!({"discord": {"guildId": null, "voiceChannelId": null}})).unwrap();
assert_eq!((s.discord.guild_id, s.discord.voice_channel_id), (None, None));
}
#[test]
fn invalid_json_names_the_file() {
let dir = std::env::temp_dir().join(format!("jarvis-settings-bad-{}", std::process::id()));
std::fs::create_dir_all(&dir).unwrap();
let path = dir.join("settings.json");
std::fs::write(&path, "{ nope").unwrap();
let e = load_settings(&path).unwrap_err();
std::fs::remove_dir_all(&dir).ok();
assert!(e.0.contains("not valid JSON"));
}
}