소리함 — 음성 녹음 아카이브(로컬 STT, 화자분리, AI 요약, 검색) — 의 백엔드입니다. 녹음 폴더를 스캔·감시해 데이터베이스에 등록하고, 변환·요약 파이프라인을 진행하는 워커와 검색·재생용 REST API를 제공합니다.
스택: Python 3.12+, FastAPI, PostgreSQL(alembic 마이그레이션, pg_trgm 검색).
cp .env.example .env # 값 채우기
docker compose up -d # postgres
uv sync
uv run alembic upgrade head
uv run soriham-api bootstrap --email [email protected] --name 이름 \
--workspace-slug mine --workspace-name 내 보관함 # 최초 1회, 첫 운영자
uv run soriham-api scan # 녹음 폴더 스캔 등록
uv run soriham-api watch # 새 파일 감시 등록
uv run soriham-api worker # 변환 파이프라인 워커 (stt 러너 필요)
# 제목/요약/태그는 기본 Ollama(qwen3), ENRICH_BACKEND로 교체
uv run soriham-api serve # REST API (기본 8200 포트)가입은 누구나 할 수 있고 관리자 승인을 받아야 쓸 수 있습니다. 로그인 세션은 httpOnly
쿠키이며, 안전하지 않은 메서드는 X-CSRF-Token 헤더를 함께 요구합니다.
| 메서드·경로 | 역할 |
|---|---|
POST /api/auth/signup · login · logout |
가입·로그인·로그아웃 |
GET /api/auth/me |
내 계정, 워크스페이스 목록, 화면이 그릴 것들 |
POST /api/auth/password |
비밀번호 변경 (다른 자리의 세션은 폐기) |
GET /api/admin/users?status= |
상태로 거른 계정 목록 |
PUT /api/admin/users/{id}/status |
승인·거절·중지·재개 |
POST /api/workspaces |
워크스페이스 생성 (서비스 관리자만) |
GET /api/workspaces/{ws}/recordings |
목록 (q, status, tag 필터, 페이지네이션) |
POST /api/workspaces/{ws}/recordings |
업로드 |
GET /api/workspaces/{ws}/tags |
태그 목록 |
GET /api/workspaces/{ws}/search?q= |
검색 (세그먼트·파일명·제목·요약) |
GET /api/workspaces/{ws}/stats |
상태별 집계, 처리 배속, ETA, 최근 에러 |
GET /api/workspaces/{ws}/usage |
사용량과 한도 (전사 시간 30일 롤링, 저장 용량) |
GET·PUT·DELETE /api/workspaces/{ws}/members… |
구성원 목록과 역할 변경, 내보내기 |
GET·POST·DELETE /api/workspaces/{ws}/invites… |
초대 발급·목록·철회 |
GET·POST /api/invites/{token}… |
초대 미리보기와 수락 |
GET /api/recordings/{id} |
상세 (세그먼트, 화자 이름, 태그) |
PATCH /api/recordings/{id} |
제목 수정 |
DELETE /api/recordings/{id} |
삭제 (업로드본은 원본 파일까지, 스캔본은 등록만) |
POST /api/recordings/{id}/retry |
실패한 녹음을 다시 큐에 (남은 산출물부터 재개) |
PUT /api/recordings/{id}/speakers/{key} |
화자 표시 이름 수정 |
GET /api/recordings/{id}/audio |
오디오 스트리밍 (Range 지원) |
POST·DELETE /api/recordings/{id}/tags… |
태그 추가·제거 |
GET·POST·DELETE /api/recordings/{id}/shares… |
사람 지정 공유 (열람·편집) |
POST·DELETE /api/recordings/{id}/links… |
공유 링크 발급·철회 |
GET /api/shared-with-me |
나에게 공유된 녹음 |
GET /api/shared/{token} · /audio |
로그인 없는 링크 열람과 재생 |
POST /api/shared/{token}/unlock |
비밀번호가 걸린 링크 열기 |
id는 전부 uuid(공개 식별자)입니다. 스캔·감시로 들어온 원본 오디오는 제자리 인덱싱하며 이동·복사하지 않고, 업로드본만 보관 폴더의 워크스페이스별 하위 경로에 저장합니다.
녹음은 워크스페이스 하나에 속합니다. 태그와 중복 판정도 워크스페이스 안에서만 이뤄집니다.
워크스페이스마다 전사 시간과 저장 용량 한도를 둘 수 있습니다. 한도를 비우면
무제한입니다. 한도를 넘긴 녹음은 quota_blocked로 서 있다가, 기간이 지나거나 한도가
오르면 워커가 다시 큐에 넣습니다.
[녹음 폴더] ──스캔·감시──▶ [soriham-api: 인제스트 + PostgreSQL]
│
▼
[soriham-api: 워커] ──HTTP 잡 API──▶ [soriham-stt: 변환 러너]
│ (whisper + 화자분리)
▼
[브라우저] ◀──▶ [soriham-console 웹 UI] ──REST──▶ [soriham-api: FastAPI]
| 레포지토리 | 역할 |
|---|---|
| soriham-api | FastAPI 백엔드와 처리 워커 (Python, PostgreSQL) |
| soriham-console | 웹 콘솔 (React, TypeScript) |
| soriham-stt | 음성 변환 러너 (whisper 계열, pyannote) |