disaster-broadcast-studio 0.1.1 → 0.2.0

package/skills/scenario-writing/references/format.md

@@ -8,6 +8,7 @@ Node.js 22 이상을 사용한다. `npm install disaster-broadcast-studio`로
 npx dbs schema --out scenario.schema.json
 npx dbs regions --search 철원 --json
 npx dbs validate scenario.yaml
+npx dbs preview scenario.yaml
 npx dbs inspect scenario.yaml --frame 360
 npx dbs frame scenario.yaml --frame 360 --out frame.png
 npx dbs render scenario.yaml --from 300 --to 599 --out clip.mp4
@@ -17,7 +18,9 @@ npx dbs credits scenario.yaml --out description-credits.txt
 
 프레임은 0부터, 구간 끝은 포함한다. 300~599는 60fps에서 5초다. `inspect`는 해당 프레임의 이야기 시각·카메라·활성 연출·문자 이력을 렌더 없이 반환한다. `regions`는 내장 대한민국 시군구 ID와 이름을 검색한다. 코드를 추측하거나 옛 행정코드를 기억으로 넣지 않는다. 예를 들어 `dbs regions --search 철원`의 결과는 `51780 철원군`이다. `--json`으로 목록을 읽고 문자열 ID를 사용한 뒤 `dbs validate scenario.yaml`로 실제 경계와 대조한다. 내장 목록은 SGIS/admdongkor 2026-07-01 경계를 시군구로 병합한 것이다. 북한의 배경 육지는 시군구 선택 목록이 아니다. 사용자 GeoJSON을 쓰면 그 파일의 Feature ID를 읽어 사용한다. `schema`의 JSON Schema가 정확한 필드 계약이다.
 
-`--browser`로 Chromium 경로를 지정할 수 있다. 생략하면 Remotion이 Chrome Headless Shell을 관리하며 최초 설치에 인터넷이 필요하다. 이후 렌더는 로컬 자산만 사용한다. Linux 소프트웨어 렌더는 `--gl swangle`, GPU는 기본 `angle`이다. `--concurrency` 기본값은 2다. `--overwrite` 없이 기존 결과와 부속 `.json`·`.credits.txt`를 덮어쓰지 않는다. 실패 시 종료코드 1과 입력 위치를 반환한다.
+`preview`는 영상 출력 없이 동일한 방송 화면·음향을 로컬 웹 페이지에서 재생한다. 출력한 주소를 브라우저에서 열고 재생·일시정지·탐색 막대·프레임 이동·컷 선택을 사용한다. 기본 주소는 `http://127.0.0.1:3000`이며 `--port <번호>`로 변경한다. `--port 0`은 빈 포트를 선택한다. 시나리오·사용자 지도·참조 음원 저장을 감지해 현재 프레임에서 일시정지한 뒤 반영한다. 전체 길이가 줄면 마지막 프레임으로 제한한다. 오류 중에는 마지막 정상 화면을 유지하고 수정하면 복구한다. Ctrl+C로 서버와 임시 자산을 정리한다. Headless Chromium은 필요하지 않으며, 지도·글꼴 로딩은 재생을 기다린다. 미리보기 재생 속도는 브라우저와 GPU 성능에 따른다.
+
+`frame`·`render`·`audio`는 `--browser`로 Chromium 경로를 지정할 수 있다. 생략하면 Remotion이 Chrome Headless Shell을 관리하며 최초 설치에 인터넷이 필요하다. 이후 렌더는 로컬 자산만 사용한다. `frame`·`render`의 Linux 소프트웨어 렌더는 `--gl swangle`, GPU는 기본 `angle`이다. `--concurrency` 기본값은 2다. `--overwrite` 없이 기존 결과와 부속 `.json`·`.credits.txt`를 덮어쓰지 않는다. 실패 시 종료코드 1과 입력 위치를 반환한다.
 
 영상과 프레임 옆 `.json`은 작품·프레임 범위·자산 출처를 기록하고, `.credits.txt`는 게시용 출처 문안이다. 지도 출처를 화면에 상시 표시하지 않으므로 유튜브 설명란 등에 이 문안을 포함한다. 동봉 지도에 적용되는 출처·제공자·라이선스·가공 내용과 작품 음원 정보를 보존한다. 사용자 자산이 화면 내 표기를 요구하면 그 조건도 별도로 충족한다.
 
@@ -55,9 +58,9 @@ YAML/JSON을 사용한다. 알 수 없는 필드와 중복 YAML 키는 오류다
 | `type` | 추가 필드 | 동작 |
 | --- | --- | --- |
 | `alert` | `sender`, `text`, `level?`, `regions?`, `corrects?`, `occurredAt?`, `publishedAt?`, `pageSeconds?`, `mapHighlight?`, `sound?` | 수신 이후 최신순 이력에 남는다. duration/carry 없음 |
-| `news` | `duration`, `source`, `headline`, `publishedAt?`, `carry?` | 하단 뉴스. 동시 1개. 최대 160자 |
-| `status` | `duration`, `items: [{text, color}]`, `carry?` | 상단 상태 박스 전체. 동시 1개 |
-| `bulletin` | `duration`, `source`, `heading`, `text`, `color?`, `pageSeconds?`, `carry?` | 지도·문자 부분을 덮는 방송 안내. 시계·상태·하단 뉴스 유지. 동시 1개 |
+| `news` | `duration`, `source`, `headline`, `publishedAt?`, `sound?`, `carry?` | 하단 뉴스. 기본 무음. 동시 1개. 최대 160자 |
+| `status` | `duration`, `items: [{text, color}]`, `sound?`, `carry?` | 상단 상태 박스 전체. 동시 1개 |
+| `bulletin` | `duration`, `source`, `heading`, `text`, `color?`, `pageSeconds?`, `sound?`, `carry?` | 지도·문자 부분을 덮는 방송 안내. 시계·상태·하단 뉴스 유지. 동시 1개 |
 
 `sender`와 `source`는 `agencies`의 ID다. 문자는 실제 수신 시각을 이벤트의 `at`으로 정한다. 발생·발표 시각을 별도로 주지 않으면 임의로 만들어 표시하지 않는다. 문자 등급은 `안전안내`(기본)·`긴급재난`·`위급재난`이다. 원문에 `[발신자 표시명]`이 있으면 그대로 사용하고, 없으면 앞에 붙인다. 별도 기관명 칸을 반복하지 않는다. 정정은 원 ID를 `corrects`로 참조하는 새 문자다. 서로 다른 기관의 상충된 주장은 데이터 오류가 아니다.
 
@@ -65,7 +68,9 @@ YAML/JSON을 사용한다. 알 수 없는 필드와 중복 YAML 키는 오류다
 
 문자와 방송 안내 본문은 100개 문자소 단위에서 자연스러운 공백을 찾아 분할하며 원문을 보존한다. `alert.pageSeconds` 기본 8초, `bulletin.pageSeconds` 기본 12초, 둘 다 최소 3초다. 장문 안내 전체 페이지가 끝나기 전에 다른 안내로 덮지 않는다. 발신자·본문·등급·정정 대상이 같은 연속 반복 문자는 매번 새 문장을 읽을 필요가 없어 다음 동일 문자까지의 읽기 간격 경고에서 제외한다. `validate`의 문자 읽기 경고를 확인한다. 방송 안내 길이도 작성자가 읽어 검토한다.
 
-상태 박스는 등장 후 약 0.55초 동안 짧은 상향 이동·명도 변화를 거쳐 자리 잡는다. 프레임 기반이며 별도 애니메이션 데이터를 작성할 필요가 없다. 상태 박스에는 문구와 `#RRGGBB` 색상만 있다. 경보 종류·단계·규칙을 엔진이 판단하지 않는다. 전체 문구를 `DEFCON 4`, `갑호비상`, `소방동원령 1호`처럼 짧게 작성한다. 배열 순서대로 나란히 표시한다. 변경할 때는 현재 이벤트 종료와 다음 이벤트 시작을 맞춘다. `items: []`나 상태 이벤트가 없는 구간에는 박스가 없다. 화면 폭에 맞는 개수와 길이로 작성하고 실제 프레임을 확인한다.
+뉴스 교체·종료, 새 문자 수신, 장문 페이지 변경, 상태의 등장·교체·해제와 방송 안내 진입·종료에는 약 0.45초의 이동·명도 전환이 기본 적용된다. 새 문자는 위에서 펼쳐지며 이전 이력을 아래로 밀어낸다. 이력으로 내려간 문자도 등급 배지·왼쪽 테두리의 색상은 유지한다. 상태는 유지되는 문구·색상을 다시 강조하지 않고 바뀐 항목만 같은 칸에서 교체한다. 새 상태는 진입 후 1.8초 동안 3회 밝기가 내려갔다 돌아오고 배경·하단 선으로 함께 강조한다. 범례·보조 지도도 부드럽게 진입한다. 종료 전환은 이벤트 종료 프레임부터 최대 약 0.45초 동안 이전 문구를 보여주며 사라진다. 모두 콘텐츠 프레임 기준이므로 시계 전환 중에는 효과도 멈추며 별도 애니메이션 데이터를 작성할 필요가 없다.
+
+상태 박스에는 문구와 `#RRGGBB` 색상만 있다. 경보 종류·단계·규칙을 엔진이 판단하지 않는다. 전체 문구를 `DEFCON 4`, `갑호비상`, `소방동원령 1호`처럼 짧게 작성한다. 배열 순서대로 나란히 표시한다. 변경할 때는 현재 이벤트 종료와 다음 이벤트 시작을 맞춘다. `items: []`나 상태 이벤트가 없는 구간에는 해제 전환 후 박스가 없다. 화면 폭에 맞는 개수와 길이로 작성하고 실제 프레임을 확인한다.
 
 ## 지도 연출
 
@@ -85,7 +90,7 @@ YAML/JSON을 사용한다. 알 수 없는 필드와 중복 YAML 키는 오류다
 
 행정구역의 채우기 불투명도 `fillOpacity` 기본 0.36, 윤곽선 `strokeColor` 기본 color, `strokeOpacity` 기본 1, `strokeWidth` 기본 2px다. 채우기 없이 경계만 표시하려면 `fillOpacity: 0`, 채우기만 표시하려면 `strokeWidth: 0`을 준다. `fadeIn`·`fadeOut`은 초 단위이며 기본 0이다. `pulse`는 채우기 밝기만 완만하게 변화시키고 테두리는 유지한다. 같은 지역에 여러 이벤트를 겹칠 수 있으며 채우기 위에 윤곽선이 놓이고 같은 종류 안에서는 이벤트 순서대로 합성한다. `legend`는 작품이 지정한 의미만 설명한다. 범례가 없으면 엔진은 자동으로 의미를 붙이지 않는다. 서로 다른 사실을 나타내는 색·선은 문안·시점·범례와 함께 작성한다.
 
-문자는 `regions`에 지정된 영역의 채우기를 수신 시 기본 2.4초 동안 부드럽게 강조한다. 테두리는 변경하지 않고 처음 약 0.2초에 나타나 마지막 약 0.7초에 사라진다. 기본 지도는 이 효과의 시작·종료에 따라 다시 그리지 않는다. `mapHighlight: {duration: 3, color: '#d6e2ec'}`로 바꾸거나 `mapHighlight: false`로 끈다. 빈 지역 목록은 강조하지 않는다. 이 효과는 짧은 수신 표시이며 지속적인 발송 이력 채우기·위기경보 경계는 별도 `region`으로 작성한다. 엔진이 기관명에서 발송 범위를 추측하지 않는다.
+문자는 `regions`에 지정된 영역의 채우기를 수신 시 기본 2.4초 동안 3회 부드럽게 점멸한다. 테두리는 유지하며 각 점멸은 채우기가 나타났다가 사라지는 형태다. 기본 지도는 이 효과의 시작·종료에 따라 다시 그리지 않는다. `mapHighlight: {duration: 3, color: '#d6e2ec'}`로 바꾸거나 `mapHighlight: false`로 끈다. 빈 지역 목록은 강조하지 않는다. 이 효과는 짧은 수신 표시이며 지속적인 발송 이력 채우기·위기경보 경계는 별도 `region`으로 작성한다. 엔진이 기관명에서 발송 범위를 추측하지 않는다.
 
 기관명은 발송 대상과 다를 수 있다. 도청이 특정 시군만 대상으로 보내면 본문에 그 시군을 명시하고 그 코드만 지정한다. ‘도 전역’ 문자는 내장 목록에서 도 소속 시군 전체를 조회해 포함한다. 모든 문자에서 본문 대상·`regions`·지속 지도 표시를 대조한다. 의도적인 불일치는 작성 근거를 작품 기록에 남기며 `mapHighlight: false`와 별도 지도 이벤트로 표현할 수 있다. 지역 강조·지점·영역·선은 여러 개를 병렬로 사용할 수 있다.
 
@@ -99,7 +104,11 @@ YAML/JSON을 사용한다. 알 수 없는 필드와 중복 YAML 키는 오류다
 | `silence` | `duration`, `carry?` | 모든 음원 음소거. 원음 재생 위치는 계속 진행 |
 | `screen` | `duration`, `effect`, `intensity?`, `fadeIn?`, `fadeOut?`, `carry?` | blackout/flash/interference/noise/scanlines/chromatic/dropout/shutdown. intensity 기본 1(0~1). 병렬 조합 가능 |
 
-음원 시작 위치와 연출은 영상 프레임에서 계산한다. 컷 경계를 넘길 음원은 carry를 지정하고 로컬 파일의 길이도 확보한다. 음원을 자동 반복하지 않는다. 큰 음량·지속적인 노이즈·잦은 섬광으로 공포를 대신하지 않는다. 문자에는 엔진이 직접 합성한 공통 수신음이 한 번 재생된다. 실제 기관 경보음을 모방한 소리가 아니다. `sound: false`로 끄거나 `sound: {asset: myTone, duration: 0.8, volume: 0.7}`로 사용자 자산을 지정한다. 기본은 `sound: default`이며 생략해도 같다. 별도 `audio` 이벤트로 수신음을 중복 삽입하지 않는다. `silence`는 공통 수신음도 음소거한다.
+음원 시작 위치와 연출은 영상 프레임에서 계산한다. 컷 경계를 넘길 음원은 carry를 지정하고 로컬 파일의 길이도 확보한다. 음원을 자동 반복하지 않는다. 큰 음량·지속적인 노이즈·잦은 섬광으로 공포를 대신하지 않는다.
+
+문자에는 등급별 기본음이 한 번 재생된다. 안전안내는 휴대폰 진동형 두 번 떨림의 0.55초, 긴급재난 2.4초, 위급재난 4.2초이며 긴급·위급은 단계적으로 더 크고 긴 EAS풍 경보다. 상태는 등장·항목 변경·해제 때 같은 높이로 두 번 울리는 짧은 전자음의 0.3초, 방송 안내는 시작 때 크고 묵직하게 두 번 울리는 1초의 알림음을 제공한다. 뉴스는 기본 무음이며 화면 전환으로 갱신을 알린다. 같은 상태를 연속 유지하면 다시 울리지 않고 교체·명시적 빈 항목 해제는 새 상태의 설정을 따른다. 자연 종료는 종료되는 상태의 설정을 따른다. 뉴스·방송 안내 종료나 장문 페이지 전환에는 추가 음이 없다.
+
+`sound: false`로 끄거나 `sound: {asset: myTone, duration: 0.8, volume: 0.7}`로 사용자 자산을 지정한다. `alert`, `status`, `bulletin`은 `sound: default`, `news`는 `sound: false`가 기본값이다. 뉴스에 `sound: default`를 명시하면 0.28초의 짧은 단음을 한 번 재생한다. 별도 `audio` 이벤트로 수신음을 중복 삽입하지 않는다. `silence`는 모든 기본 효과음도 음소거한다.
 
 `shutdown`은 송출 화면을 최대 1.5초 동안 가로선→작은 점으로 수축하고 이벤트 종료까지 검은 화면을 유지한다. 전체 영상을 종료하는 효과가 아니므로 결말에서 충분한 duration을 지정한다. 신호가 사라지기 직전의 정보·음향·이후 침묵까지 작품 흐름으로 구성한다.