Files
game_voice_recorder/packages/shared/src/protocol.ts

567 lines
19 KiB
TypeScript

import type { PlayerRating } from './rating.js';
// 앱 코어 · 사이트 서버 · 사이트 프런트엔드가 같이 쓰는 타입. docs/dev/ARCHITECTURE.md 4~6장.
export type GameType = 'valorant' | 'lol';
export interface TimeLabel {
/** 발로란트 "R7 · 0:42" / 롤 "21:14" / 경기 밖 "21:08:44" */
primary: string;
/** 발로란트 경기 경과 시간 "12:18" */
secondary?: string;
/** 현실 시각 (unix ms) */
real: number;
}
export interface Word {
w: string;
/** 발화 시작 기준 초 */
s: number;
e: number;
p?: number;
}
export interface User {
id: string;
name: string;
color: string;
avatar: string | null;
excluded: boolean;
riot: { puuid: string; riotId: string }[];
}
export type UtteranceStatus = 'pending' | 'realtime' | 'precise' | 'failed';
/** 발화 자세한 정보 (사이트 우클릭 → 자세한 정보, v1.3.6~) */
export interface UtteranceInfo {
id: string;
userId: string;
/** 원본 음성 파일 이름 (예: 0mv9wpior2f765541ac.ogg) */
fileName: string | null;
/** 게임 PC 안의 전체 경로 */
path: string | null;
/** 파일이 있는 폴더 */
folder: string | null;
/** 파일 크기 (바이트), 지워졌으면 null */
sizeBytes: number | null;
/** 파일이 지워진 이유: 보관 기간 · 잡음 · 파일 없음 */
deleted: null | 'retention' | 'noise' | 'missing';
startedAt: number;
endedAt: number;
durationMs: number;
/** 녹음 세션 · 음성채널 */
sessionId: string | null;
channel: string | null;
matchId: string | null;
status: string;
model: string | null;
confidence: number | null;
lufs: number | null;
gainDb: number | null;
/** 사전 교정 전 원래 인식 결과 */
rawText: string | null;
text: string | null;
corrected: boolean;
noise: boolean;
noiseReason: string | null;
attempts: number;
createdAt: number;
}
export interface UtteranceItem {
kind: 'utterance';
id: string;
ts: number;
endTs: number;
userId: string;
text: string | null;
words: Word[];
noise: boolean;
status: UtteranceStatus;
corrected: boolean;
confidence: number | null;
model: string | null;
audio: { url: string; durationMs: number; gainDb: number } | null;
game: { type: GameType; matchId: string; round?: number } | null;
time: TimeLabel;
}
export type EventType =
| 'kill'
| 'chat'
| 'object'
| 'spike'
| 'round_end'
| 'match_start'
| 'match_end'
| 'multikill'
| 'ace';
export interface PlayerRef {
puuid?: string;
name: string;
team?: string;
/** 발로란트 요원 / 롤 챔피언 */
character?: { id: string; name: string; icon: string | null };
userId?: string;
}
export interface KillData {
killer: PlayerRef | null;
victim: PlayerRef;
assists: PlayerRef[];
weapon: { id: string; name: string; icon: string | null } | null;
headshot?: boolean;
location?: { x: number; y: number } | null;
ally?: boolean;
}
export interface ChatData {
sender: PlayerRef;
channel: 'team' | 'all' | 'party' | 'system';
text: string;
source: 'api' | 'ocr' | 'lcu' | 'log';
}
export interface ObjectData {
object: 'dragon' | 'baron' | 'herald' | 'grub' | 'tower' | 'inhibitor' | 'atakhan';
subtype?: string;
team?: string;
killer?: PlayerRef | null;
ally?: boolean;
}
export interface RoundEndData {
round: number;
win: boolean;
result: string;
score: { ally: number; enemy: number };
}
export interface EventItem {
kind: 'event';
id: string;
ts: number;
game: GameType;
matchId: string;
type: EventType;
data: any;
time: TimeLabel;
userId?: string;
}
export type TimelineItem = UtteranceItem | EventItem;
export interface TimelinePage {
items: TimelineItem[];
next: string | null;
}
export interface MatchSummary {
id: string;
game: GameType;
startedAt: number;
endedAt: number | null;
map: { id: string; name: string; image: string | null };
mode: string;
win: boolean | null;
score: { ally: number; enemy: number } | null;
status: 'live' | 'pending_detail' | 'complete';
participants: string[];
}
export interface MatchPlayer {
puuid: string;
name: string;
tag?: string;
team: string;
ally: boolean;
character: { id: string; name: string; icon: string | null };
kills: number;
deaths: number;
assists: number;
score?: number;
cs?: number;
gold?: number;
level?: number;
items?: { id: number; name: string; icon: string | null }[];
rank?: string | null;
userId?: string;
/** 범인찾기용 추가 지표 (v1.3~ 에 저장한 경기만 있다) */
stats?: PlayerStats;
}
/** 경기 상세에서 더 저장하는 지표. 예전 경기는 없다 (범인찾기는 "기본 기록으로 분석"으로 표시) */
export interface PlayerStats {
/** 발로란트: 요원 역할(타격대·척후대·전략가·감시자) / 롤: 포지션(탑·정글·미드·원딜·서폿, 추정) */
role?: string;
/** 발로란트: 준 피해 합 / 롤: 챔피언에게 준 피해 */
damage?: number;
rounds?: number;
// 발로란트
headshotPct?: number;
firstKills?: number;
firstDeaths?: number;
plants?: number;
defuses?: number;
abilityCasts?: number;
/** 발로란트: KAST(킬 · 어시 · 생존 · 트레이드)를 한 라운드 수 (v1.3~) */
kastRounds?: number;
/** 롤 · 발로란트(v1.3~): 받은 피해 */
damageTaken?: number;
// 롤
vision?: number;
wardsPlaced?: number;
wardsKilled?: number;
controlWards?: number;
objectiveDamage?: number;
turretDamage?: number;
ccSeconds?: number;
at10?: { cs: number; gold: number; xp: number };
at15?: { cs: number; gold: number; xp: number };
}
export interface MatchRound {
num: number;
startedAt: number;
endedAt: number;
win: boolean;
result: string;
score: { ally: number; enemy: number };
economy?: Record<string, { spent: number; remaining: number; weapon?: string; loadout?: number }>;
/** 이 라운드에서 우리 팀이 공격이었나 (v1.3~) */
allyAttack?: boolean;
/** 선수별 이 라운드 킬 · 준 피해 (v1.3~) */
players?: Record<string, { kills: number; damage: number }>;
}
export interface MatchDetail extends MatchSummary {
players: MatchPlayer[];
rounds?: MatchRound[];
goldDiff?: { t: number; diff: number }[];
events: EventItem[];
utterances: UtteranceItem[];
mapTransform:
| { valorant: { xMultiplier: number; yMultiplier: number; xScalarToAdd: number; yScalarToAdd: number } }
| { lol: { minX: number; minY: number; maxX: number; maxY: number } }
| null;
}
/** 지금 연결된 게임 · 진행 중인 경기 (앱 게임 연동 탭 · 사이트, v1.3.6~) */
export interface LiveGame {
game: GameType;
/** 연동을 켰는지 */
enabled: boolean;
/** 게임 클라이언트(Riot 클라이언트 · 롤 클라이언트)에 연결됨 */
connected: boolean;
/** 지금 상태: 꺼짐 · 메뉴 · 대기열 · 요원 선택 · 경기 중 · 경기 끝 … */
phase: string;
inMatch: boolean;
matchId: string | null;
/** 모드 이름 (경쟁전, 신속플레이, 데스매치, 솔로 랭크, 칼바람 나락 …) */
mode: string | null;
map: string | null;
mapImage: string | null;
/** 경기 시작 시각 (PC 시계) */
startedAt: number | null;
/** 발로란트 라운드제 모드: 지금 라운드 */
round: number | null;
/** 발로란트 점수. 라운드제는 팀 점수, 데스매치 등은 게임이 주는 점수 */
score: { ally: number; enemy: number } | null;
/** 롤: 게임 시간(초) */
gameTimeSec: number | null;
/** 롤: 팀 킬 */
teamKills: { ally: number; enemy: number } | null;
/** 내 계정 · 요원/챔피언 · 성적 */
self: { name: string | null; character: string | null; characterImage: string | null; kda: string | null; extra: string | null } | null;
/** 경기 인원 */
players: number | null;
/** 마지막 오류 (연결 실패 등) */
error: string | null;
updatedAt: number;
}
/** 기록 묶음 (사이트 기록 관리, v1.3.7~): 경기 하나 또는 경기 밖 대화 한 덩어리 */
export interface BundleInfo {
/** match-<경기ID> 또는 talk-<첫 발화ID> */
id: string;
kind: 'match' | 'talk';
/** "발로란트 · 경쟁전 · 어센트" · "경기 전 대화" · "경기 후 대화" · "게임 밖 대화" */
label: string;
/** 경기: "승리 13:9", 대화: "다음 경기: 발로란트 어센트" */
sub: string | null;
game: GameType | null;
matchId: string | null;
from: number;
to: number;
/** 보이는 발화 수 (잡음 뺌) */
utterances: number;
/** 음성 파일이 남은 발화 수 */
audio: number;
audioBytes: number;
/** 경기 이벤트 수 (킬 · 라운드 …) */
events: number;
talkMs: number;
users: string[];
/** 진행 중인 경기 (지울 수 없음) */
live: boolean;
}
export interface BundleImportResult {
bundles: string[];
added: { utterances: number; audio: number; matches: number; events: number; users: number };
/** 이미 있어서 건너뛴 발화 */
skipped: number;
}
export interface Overview {
guild: { id: string; name: string; icon: string | null } | null;
recording: { active: boolean; channel: string | null; since: number | null; participants: string[] };
users: User[];
games: { valorant: { connected: boolean; inMatch: boolean }; lol: { connected: boolean; inMatch: boolean } };
/** 지금 게임 상태 (v1.3.6~ 앱만 보냄) */
live?: LiveGame[];
counts: { utterances: number; matches: number };
version: string;
}
export interface UserProfile {
user: User;
stats: { talkMs: number; count: number; topWords: { w: string; n: number }[] };
matches: MatchSummary[];
}
// ------------------------------------------------------------------ 범인찾기 (계획서 v1.1)
/** ready = 분석 가능, done = 분석 완료, pending = 준비 중(경기 진행 · 음성 변환), blocked = 기록 부족 */
export interface CulpritEligibility {
state: 'ready' | 'done' | 'pending' | 'blocked';
reasons: string[];
}
export interface CulpritPlayer {
/** P1~P10 (우리 팀 먼저) */
id: string;
puuid: string;
name: string;
team: 'ally' | 'enemy';
character: { id: string; name: string; icon: string | null } | null;
userId: string | null;
/** 이 경기 음성 대화가 있는지 */
voice: boolean;
/** 기록 점수: OP.GG OP스코어 계산법을 따라 우리 기록에서 계산 (v1.3~) */
rating?: PlayerRating;
}
/** 근거 번호가 가리키는 것 (사이트에서 누르면 그 순간으로 이동) */
export type CulpritRefTarget =
| { kind: 'utterance'; id: string; ts: number }
| { kind: 'event'; id: string; ts: number; round?: number }
| { kind: 'round'; round: number; ts: number }
| { kind: 'stat'; pid: string };
/** 앱이 만든 AI 입력 (사이트 서버만 받는다) */
export interface CulpritInput {
game: GameType;
text: string;
refs: Record<string, CulpritRefTarget>;
players: CulpritPlayer[];
stats: { utterances: number; utterancesTotal: number; events: number; chats: number; rounds: number; basic: boolean };
}
export interface CulpritEvidence {
ref: string;
note: string;
target?: CulpritRefTarget;
}
export const CULPRIT_TAGS = ['캐리', '숨은 MVP', '클러치', '무난', '아쉬움', '범인'] as const;
export interface CulpritResult {
summary: string;
confidence: 'high' | 'medium' | 'low';
confidence_note: string;
teams: { team: 'ally' | 'enemy'; culprit: string; reason: string; evidence: CulpritEvidence[] }[];
players: { id: string; score: number; tag: (typeof CULPRIT_TAGS)[number]; comment: string; evidence: CulpritEvidence[] }[];
}
export interface CulpritAnalysis {
id: string;
matchId: string;
createdAt: number;
createdBy: { id: string; name: string };
model: string;
result: CulpritResult;
players: CulpritPlayer[];
meta: {
tone?: string;
durationMs?: number;
costUsd?: number;
usage?: { input: number; output: number; cacheRead?: number; cacheWrite?: number };
inputStats?: CulpritInput['stats'];
fallback?: boolean;
};
}
export interface CulpritMatchItem {
match: MatchSummary;
eligibility: CulpritEligibility;
culprits: { team: 'ally' | 'enemy'; name: string; character: { id: string; name: string; icon: string | null } | null }[];
}
export interface CulpritMatchInfo {
match: MatchSummary;
eligibility: CulpritEligibility;
sources: { rounds: number | null; events: number; utterances: number; chats: number; extraStats: boolean };
players: CulpritPlayer[];
analysis: CulpritAnalysis | null;
history: { id: string; at: number; by: { id: string; name: string }; model: string; current: boolean }[];
}
/** 사이트 서버의 예산 · 권한 (GET /api/culprit/budget) */
export interface CulpritBudget {
enabled: boolean;
canAnalyze: boolean;
canReanalyze: boolean;
monthSpentUsd: number;
monthLimitUsd: number;
todayCount: number;
dailyLimit: number;
estimateUsd: number;
model: string;
running: string[];
}
export type CulpritStage = 'collect' | 'thinking' | 'verify' | 'done' | 'failed';
export type LiveEvent =
| { type: 'culprit.progress'; data: { matchId: string; stage: CulpritStage; message?: string } }
| { type: 'utterance.created' | 'utterance.updated'; data: UtteranceItem }
| { type: 'event.created'; data: EventItem }
| { type: 'match.updated'; data: MatchSummary }
| { type: 'recording.state'; data: Overview['recording'] }
| { type: 'users.updated'; data: User[] }
| { type: 'games.state'; data: LiveGame[] }
| { type: 'records.changed'; data: { reason: 'deleted' | 'imported'; ids?: string[] } }
/** 사이트 우클릭으로 발화 하나를 지움 (v1.4.0). noise = "잡음이라 삭제" */
| { type: 'utterance.deleted'; data: { id: string; noise: boolean } };
/** "잡음이라 삭제"로 배운 문장 (GET /api/noise-phrases) */
export interface NoisePhrase {
id: number;
text: string;
/** 그 뒤로 이 문장을 잡음으로 걸러 낸 횟수 */
hits: number;
createdAt: number;
}
export interface DeviceStatus {
registered: boolean;
online: boolean;
name: string | null;
lastSeen: number | null;
version: string | null;
}
export type BrowserMessage = { type: 'status'; data: { device: DeviceStatus } } | LiveEvent;
// 사이트 서버 ↔ 앱 WebSocket
export type RelayToDevice =
| {
t: 'req';
id: string;
method: string;
path: string;
headers: Record<string, string>;
user: { id: string; name: string; avatar: string | null } | null;
body: string | null;
/** 본문이 바이너리(zip 등)면 true. 본문은 이 메시지 앞에 같은 id 의 바이너리 조각으로 먼저 온다 (v1.3.7~) */
bin?: boolean;
}
| { t: 'cancel'; id: string }
| { t: 'pong'; ts: number }
| { t: 'welcome'; deviceId: string };
export type RelayFromDevice =
| { t: 'hello'; name: string; version: string; guildId?: string | null }
| { t: 'ping'; ts: number }
| { t: 'res'; id: string; status: number; headers: Record<string, string>; body: string | null }
| { t: 'res_head'; id: string; status: number; headers: Record<string, string> }
| { t: 'res_end'; id: string }
| { t: 'event'; event: LiveEvent };
// 앱(exe) 로그인 · 유저 등록 (사이트 서버 /auth/app/*, /app/*)
/** superadmin = 최고 관리자(서버에 고정), admin = 관리자, user = 일반 유저 */
export type AppRole = 'superadmin' | 'admin' | 'user';
export interface AppUserInfo {
id: string;
name: string;
avatar: string | null;
}
/** POST /auth/app/begin → 브라우저로 열 주소와 결과를 받아 갈 비밀값 */
export interface AppLoginBegin {
id: string;
secret: string;
url: string;
expiresAt: number;
}
/** POST /auth/app/poll 응답 */
export type AppLoginPoll =
| { state: 'pending' }
| { state: 'ok'; token: string; user: AppUserInfo; role: AppRole }
| { state: 'not_registered'; user: AppUserInfo }
| { state: 'error'; error: string };
/** GET /app/me 응답 (등록된 유저만). 겜녹이 봇 토큰은 내려주지 않는다 (봇은 서버가 대신 연결, 아래 BotGw*) */
export interface AppMe {
user: AppUserInfo;
role: AppRole;
serverTime: number;
}
/** 관리자 화면의 등록 유저 한 줄 */
export interface AppUserRow {
id: string;
name: string;
avatar: string | null;
role: AppRole;
/** 서버에 고정된 최고 관리자 (지우거나 역할을 바꿀 수 없음) */
fixed: boolean;
addedBy: string | null;
addedAt: number | null;
lastSeenAt: number | null;
lastVersion: string | null;
}
// 겜녹이 봇 중계 (사이트 서버 WebSocket /app/bot/ws, Authorization: Bearer <앱 토큰>)
// 권한: 앱 유저가 가입한 디스코드 서버만, 그 유저가 볼 수 있는 채널만 보이고, 들어갈 수 있는(보기 + 연결) 음성채널에만 봇을 부를 수 있다
// 봇 토큰은 서버에만 있다. 서버가 디스코드 게이트웨이에 붙어 있고, 앱은 필요한 정보만 받는다.
// 음성채널에 들어갈 때는 앱의 @discordjs/voice 가 보낸 op 4 를 서버가 대신 보내고,
// 디스코드가 준 일회용 음성 접속 정보(VOICE_STATE/SERVER_UPDATE)를 앱에 넘긴다. 음성은 앱 ↔ 디스코드로 바로 간다.
export interface BotGwMember {
id: string;
name: string;
avatar: string | null;
bot: boolean;
}
export interface BotGwGuild {
id: string;
name: string;
icon: string | null;
}
export interface BotGwChannel {
id: string;
name: string;
}
export type BotGwToApp =
| { t: 'ready'; me: BotGwMember; guilds: BotGwGuild[] }
| { t: 'guilds'; guilds: BotGwGuild[] }
/** watch 응답: 그 서버에서 이 유저가 볼 수 있는 음성채널 · 그 채널에 있는 사람 */
| { t: 'guild'; guild: BotGwGuild; channels: BotGwChannel[]; voice: { member: BotGwMember; channelId: string }[] }
/** watch 거절: 이 유저가 가입하지 않은 서버 */
| { t: 'watch_denied'; guildId: string }
| { t: 'voiceState'; guildId: string; member: BotGwMember; oldChannelId: string | null; newChannelId: string | null; channel: BotGwChannel | null }
| { t: 'cmd'; id: string; name: string; guildId: string; user: BotGwMember; voiceChannel: BotGwChannel | null }
/** 음성 접속 정보 (디스코드 VOICE_SERVER_UPDATE / 봇 자신의 VOICE_STATE_UPDATE 원문) */
| { t: 'vserver'; guildId: string; data: any }
| { t: 'vstate'; guildId: string; data: any }
/** 다른 PC 가 이 서버에서 봇을 데려갔다 → 녹음을 멈춘다 */
| { t: 'taken'; guildId: string }
| { t: 'res'; id: string; ok: boolean; data?: any; error?: string };
export type BotGwFromApp =
| { t: 'watch'; guildId: string; commands: boolean }
/** @discordjs/voice 어댑터가 보낸 게이트웨이 op 4 (음성채널 참여 · 나가기) */
| { t: 'voice'; guildId: string; payload: any }
| { t: 'cmd_res'; id: string; content: string }
| { t: 'req'; id: string; op: 'members'; guildId: string };