현재 문서 오디오와 재생 전체 가이드

이 장에서 만드는 것

Markdown 문서 한 개를 제목 단위 chunk로 나누고, 현재 locale에서 읽을 수 있는 구간의 오디오를 만든다. 생성 전에는 runtime과 기본 음성을 확인하고, 생성 뒤에는 문서 전체 queue를 속도별로 미리 듣는다. 실패가 생기면 성공한 chunk는 보존하고 실패 항목만 다시 시도한다.

오디오는 원문을 바꾸는 기능이 아니다. 원문 Markdown이 정본이며 WAV와 생성 상태는 원문·locale·voice identity에서 다시 만들 수 있는 파생 자산이다.

이 장의 화면은 실제 Glif release candidate에서 audio-lab을 연 결과다. 현재 개발 빌드는 공식 signed audio package가 없어 runtime 미준비, chunk 분류와 locale 상태까지만 실제 UI로 검증한다. package 설치·실제 생성·재생 성공은 qualified release artifact가 있는 환경에서 별도로 통과해야 한다.

준비물

• 제목과 본문이 있는 Markdown 문서
• 현재 문서를 포함한 Binder
• 현재 locale을 지원하는 Glif 공식 오디오 runtime package와 기본 voice
• 첫 생성에 필요한 저장 공간

현재 문서 오디오 실습 Binder 열기

fixture에는 speakable 문서, code-only 문서와 locale 발음 검토 문서가 있다. runtime, voice model, 생성 WAV, 계정 상태와 credential은 포함하지 않는다.

오디오 상태를 읽는 네 축

축	질문	확인할 값
runtime	음성 엔진과 package를 실행할 수 있는가	준비됨, 설치 필요, package 없음, 확인 필요
voice	현재 기본 음성이 locale을 지원하는가	지원 locale, 실험적 locale, voice/profile identity
문서	어떤 Markdown을 읽는가	Binder 상대 문서 경로, 문서 키, heading chunk
coverage	지금 들을 수 있는가	speakable, available, missing, skipped, failed

available / speakable은 전체 Markdown 구간 수가 아니다. 예를 들어 3/3 chunk 사용 가능, TTS 제외 1개라면 읽을 본문 3개는 모두 준비됐고 code-only 구간 1개는 의도적으로 제외됐다는 뜻이다.

현재 지원 범위

작업	현재 문서 v1	현재 범위 밖
runtime	공식 optional package 준비 상태·설치·재시도	사용자가 임의 binary나 model을 기본 runtime으로 등록
voice	설치 package의 기본 voice와 locale capability 표시	voice catalog, 임의 voice 선택, 발음 사전
생성	현재 연 Markdown의 missing speakable chunk 생성	Binder 전체 일괄 생성
재생	앱에서 현재 문서 queue 미리듣기와 속도 변경	Knowledge Radio
게시	별도 Pro/user-owned publish 계약에서 완성 자산 사용	문서별 audio 포함·제외 정책

AU-07 Binder 일괄 오디오, AU-08 voice catalog·발음 사전, AU-09 문서별 게시 포함·제외는 post-v1 deferred다. 이 장에서는 현재 기능처럼 실행 절차를 제공하지 않는다.

음성 파일을 Markdown 전사로 가져오는 연구 경계

메인 개발 트리에는 음성 파일을 source로 받아 transcript 후보를 만드는 내부 P0 검증 작업이 추가되어 있다. 현재는 입력 protocol과 isolated parser/runtime fixture의 준비 상태를 확인하는 단계이며, 앱 UI·Binder 쓰기·실제 음성 runtime delivery가 공개 계약으로 닫히지 않았다. 따라서 이 기능을 현재 오디오 가져오기나 전사 명령으로 따라 하지 않는다.

공개 가이드에 추가할 수 있는 것은 다음 release gate가 모두 닫힌 뒤다.

1. 정확한 runtime·model·corpus·license와 signed package를 확정한다.
2. 실제 audio fixture에서 품질·성능·긴 파일·실패 복구를 검증한다.
3. transcript의 source authority, 사용자 승인, Binder write와 history를 앱 표면에서 확인한다.
4. 원본 음성·전사 후보·credential이 공개 evidence와 Hugo 결과에 섞이지 않는지 확인한다.

그 전까지는 현재 문서 오디오(AU-01~AU-06)의 source-backed chunk 흐름만 사용하고, 음성 입력 전사는 연구/내부 검증으로 구분한다.

1. 실습 문서 열기

1. audio-lab 폴더를 Binder로 연다.
2. 01_listening-tour.md를 연다.
3. 문서가 저장된 상태인지 확인한다.
4. Launcher에서 오디오를 찾아 패널을 연다.

오디오 패널은 현재 Binder와 현재 Markdown을 기준으로 상태를 계산한다. Binder가 없거나 Markdown 문서가 선택되지 않았다면 먼저 열어야 할 대상을 안내하며, 다른 파일 형식을 자동 변환하지 않는다.

2. runtime 준비 상태 확인

패널 상단 경고와 오디오 런타임 패키지 절을 함께 읽는다.

표시	의미	다음 행동
준비됨	package, engine과 기본 voice가 현재 검증을 통과	locale과 coverage 확인
패키지 설치 필요	검증 가능한 source가 있고 첫 설치가 필요	패키지 설치 또는 생성 흐름 계속
패키지 없음	이 빌드에 설치할 공식 package가 없음	qualified build/package를 사용
확인 필요	설치 상태 또는 package 검증 실패	상태 새로고침 후 안내에 따라 복구

사용자는 Python, Piper executable이나 voice model 경로를 직접 맞추지 않는다. release build는 신뢰된 HTTPS catalog, signature, 파일 hash inventory, SBOM과 attribution을 검증한 뒤 managed 폴더에 atomic install한다. 화면에 준비됨이 표시되기 전에는 생성 성공을 가정하지 않는다.

설치 진행과 실패

설치 가능한 package가 있으면 오디오 런타임 패키지 설치를 선택한다. catalog 확인, 다운로드, 파일·법적 메타데이터 검증, 설치와 준비 완료 상태가 순서대로 표시된다. 설치가 실패하면 상태를 새로고침하고 같은 공식 source로 다시 시도한다. 임의 local binary를 복사해 준비됨 상태를 만들지 않는다.

3. 기본 voice와 locale 확인

runtime이 준비되면 기본 음성에 voice가 지원하는 언어가 표시된다. locale은 앱 UI 언어가 아니라 Binder에서 현재 선택한 문서 언어다.

• 지원 locale은 일반 생성 대상이다.
• 실험적 locale은 badge와 함께 표시하며 발음·성능을 더 엄격하게 검토한다.
• 목록에 없는 locale에서는 생성 버튼을 열지 않는다.
• locale 또는 voice identity가 바뀌면 이전 WAV를 현재 결과로 재사용하지 않는다.

현재 package가 지원하는 locale만 generation-ready다. 다른 locale의 오디오가 디스크에 남아 있어도 선택 locale의 fallback 음성으로 자동 재생하지 않는다.

4. speakable, missing과 skipped 구분

Glif는 Markdown을 heading-scoped chunk로 나눈 뒤 음성 입력으로 의미 있는 본문을 찾는다.

상태	의미	예시
speakable	실제로 읽을 본문이 있는 chunk	문단, 목록, 링크 표시 문구
available	현재 source와 voice identity에 맞는 WAV가 있음	생성 또는 재사용 완료
missing	speakable이지만 맞는 WAV가 없음	첫 생성 전, 원문·voice 변경 뒤
skipped	제목 외에 읽을 본문이 없음	code-only, URL-only, markup-only 구간
failed	engine 또는 저장 단계에서 생성 시도가 실패	복구 목록에서 원인 범주 확인

01_listening-tour.md에는 heading chunk가 4개 있다. 첫째, 둘째와 넷째는 읽을 본문이 있어 speakable이고, 셋째 실행 예제는 fenced code만 있어 skipped다. 따라서 첫 실행 전 기대값은 사용 가능 0 / speakable 3, 누락 3, TTS 제외 1이다.

5. locale별 audio 현황 비교

Locale별 Audio 현황은 선택 locale과 runtime voice가 제공하는 다른 locale의 coverage를 비교한다.

• 현재 선택 badge가 붙은 locale을 먼저 확인한다.
• 실험적 badge가 있으면 실제 발음 검토를 완료하기 전 게시 품질로 간주하지 않는다.
• available 수가 같아도 다른 voice/profile에서 만든 asset은 재사용할 수 없다.
• 폴더 경로는 로컬 derived storage이며 Markdown 링크로 복사하지 않는다.

공식 voice가 아직 준비되지 않은 빌드에서도 현재 선택 locale의 문서 coverage는 표시한다. qualified runtime에서 voice profile을 읽으면 지원·실험 locale별 카드가 함께 나타난다.

6. 현재 문서의 누락 오디오 생성

runtime, voice와 locale이 준비된 뒤 다음 순서로 실행한다.

1. 누락된 오디오 모두 생성을 선택한다.
2. 현재 문서와 locale을 다시 확인한다.
3. 진행 중인 chunk, 생성·재사용·제외·실패 수를 본다.
4. 완료 경고에서 available / speakable이 맞는지 확인한다.
5. 일부 실패가 있으면 성공한 WAV를 삭제하지 않고 복구 절차로 이동한다.

생성기는 heading chunk를 분류하고, source hash와 voice cache identity가 같은 기존 WAV를 재사용하며, missing만 새로 만든다. source 또는 voice가 달라진 stale asset은 현재 coverage에서 제외한다.

진행 중 취소

생성 중에는 생성 취소가 나타난다. 취소가 관측될 때까지 완료된 chunk와 이미 기록된 실패는 보존된다. 취소 뒤에는 상태를 새로고침하고 남은 missing 전체를 다시 생성한다. running 또는 cancelled snapshot에서 실패 항목만 재시도하지 않는다.

7. 문서 queue 미리듣기

available chunk가 하나 이상이면 미리듣기가 나타난다.

1. 첫 chunk를 재생한다.
2. queue에서 현재 heading과 순서를 확인한다.
3. 0.75x, 1x, 1.25x, 1.5x, 2x 속도를 비교한다.
4. 중간 chunk를 직접 선택해 이동한다.
5. 마지막 available chunk가 끝난 뒤 처음으로 되돌아가지 않는지 확인한다.

자동 이어듣기는 다음 available chunk로만 이동한다. asset을 불러오지 못하거나 브라우저가 play()를 거부하면 무한 재시도하지 않고 선택된 paused 상태로 남긴다.

8. 원문 또는 voice 변경 뒤 재생성

오디오 cache identity에는 source hash, locale, voice, package version과 engine profile이 포함된다.

• 문장 하나를 고치면 해당 heading chunk만 missing으로 돌아간다.
• voice 또는 package identity가 달라지면 기존 asset을 다른 목소리의 결과로 재사용하지 않는다.
• 변경되지 않은 chunk와 같은 voice identity의 WAV는 재사용한다.
• stale 파일 정리는 생성 흐름이 담당하며 사용자가 hash 파일명을 직접 맞추지 않는다.

재생성 뒤에는 바뀐 chunk뿐 아니라 앞뒤 문장 연결과 음량 차이도 들어본다.

9. 일부 실패 복구

terminal generation에 실패가 남으면 오디오 복구가 표시된다.

1. heading별 실패 항목과 runtime 시작, 처리, 출력, 저장 범주를 확인한다.
2. 실패한 항목 다시 시도로 기록된 실패만 재실행한다.
3. 아직 한 번도 시도하지 않은 missing까지 만들려면 누락된 오디오 모두 생성을 사용한다.
4. source가 바뀌어 stale이면 상태를 새로고침하고 일반 생성을 실행한다.

실패 snapshot에는 원문 text, 절대 model 경로, stderr, stdin과 OS 오류 문자열을 저장하지 않는다. corrupt 상태는 일반 생성으로 새 snapshot을 만들 수 있지만, 더 최신 schema인 unsupported 상태는 앱을 업데이트하기 전 생성하지 않는다.

10. 저장 위치와 직접 편집 경계

현재 문서 오디오는 Binder의 .glif/audio/<locale>/<documentKey>/ 아래에 저장된다.

항목	역할	직접 편집
chunk-....wav	source·voice identity가 맞는 파생 음성	편집하지 않음
generation-state.v1.json	현재 문서 실패·취소 복구 snapshot	편집하지 않음
Markdown 원문	모든 오디오의 정본	일반 편집 가능

오디오 폴더의 파일을 복사하거나 이름을 바꿔 available 상태를 만들지 않는다. Glif가 source hash, voice identity와 WAV 유효성을 함께 확인한다. .glif/audio는 문서 원문과 같은 canonical content가 아니며 필요하면 다시 만들 수 있다.

11. 앱 미리듣기와 공개 사이트 재생 구분

Free에서 보장하는 범위는 현재 문서의 local 생성과 앱 미리듣기다. 공개 사이트 player와 user-owned Pages의 audio artifact는 별도 Pro publish capability 뒤에 있다.

정적 Hugo 사이트는 missing audio를 생성하지 않는다. 유효한 manifest와 available asset을 재생하고, 일부 missing·network·decode 오류를 사용자에게 보여주며 같은 항목을 수동으로 다시 시도하게 한다. manifest 404 또는 진짜 empty만 정상적인 오디오 없음으로 숨긴다.

이 장은 AU-09 문서별 게시 포함·제외를 현재 설정으로 설명하지 않는다. site-level publish와 공개 player는 게시 장의 확정된 commercial·delivery 계약을 따른다.

문제 해결

증상	확인할 것	조치
패널에 문서 상태가 없다	Binder, 현재 문서 확장자	Binder 안의 Markdown을 열고 상태 새로고침
패키지 없음으로 표시된다	build에 공식 catalog/package가 있는지	qualified release build를 사용하고 임의 binary로 우회하지 않음
생성 버튼이 비활성이다	runtime, voice, locale, speakable 수	준비 상태를 순서대로 해결
생성 대상이 0개다	code-only 또는 빈 heading	읽을 본문을 추가하거나 의도한 skipped로 유지
모두 누락으로 돌아갔다	source, locale, voice/package 변경	현재 identity로 missing 생성
일부만 생성됐다	오디오 복구의 실패 범주	실패 항목만 재시도하거나 전체 missing 생성
재생이 다음 chunk로 이어지지 않는다	다음 available asset, browser play 허용	queue에서 다음 항목을 직접 선택하고 재생
다른 locale 음성이 재생되지 않는다	현재 선택 locale	fallback하지 않는 정상 동작이므로 해당 locale 생성

기능별 실증 범위

기능 ID	이 장의 절	현재 evidence
AU-01	2	실제 package-unavailable UI와 설치·검증 계약, signed artifact 실행은 release qualification 필요
AU-02	3, 8	voice/profile 표시·cache identity 구현과 절차, 실제 voice UI는 qualified package 필요
AU-03	4, 6	실제 문서 4 chunk와 coverage UI
AU-04	3, 5	실제 선택 locale과 locale summary UI
AU-05	6, 7	실제 생성 CTA·진행·재생 절차, 성공 생성은 qualified package 필요
AU-06	4, 9	실제 speakable 3·missing 3·skipped 1 분류와 복구 계약

완료 기준

• runtime의 준비됨, 설치 필요와 package 없음을 구분했다.
• 현재 voice가 선택 locale을 지원하는지 확인했다.
• speakable, available, missing, skipped와 failed를 설명할 수 있다.
• fixture가 3 speakable / 1 skipped인지 확인했다.
• qualified runtime 환경에서 missing chunk 생성과 재사용을 확인했다.
• available queue를 속도별로 미리 듣고 마지막 chunk 종료를 확인했다.
• 일부 실패 시 성공 chunk를 보존한 채 실패 항목만 재시도했다.
• source 또는 voice 변경 뒤 stale asset이 제외되는지 확인했다.
• Binder batch, voice catalog·발음 사전과 문서별 게시 정책을 현재 기능으로 오해하지 않는다.

다음 단계에서는 생성된 audio가 필요한 게시 target에서만 포함되는지 확인하고, 공개 Hugo player의 missing·network·decode 복구 흐름을 검증한다.