feat: streamline arbitrary audio sources

apps/dataset-builder/README.md

@@ -12,14 +12,19 @@
 ## 기본 사용법
 
 1. **배경 이미지**를 선택하거나 이미지 없이 grid를 사용합니다.
-2. **오디오 추가**로 source 또는 ambient에 사용할 파일을 연결합니다.
-3. **+ 음원 추가**를 누르고 카드를 선택한 뒤 canvas를 클릭하거나 x/y/z를 입력합니다.
-4. source 종류를 설정합니다.
+2. 녹음 파일을 음원으로 쓸 때는 **+ 오디오 파일 음원**을 누르고 파일을 선택합니다. 파일 asset과
+   이를 사용하는 source가 함께 생성되고 새 source가 자동으로 선택됩니다.
+3. 합성 신호가 필요하면 **+ 합성 음원**을 누릅니다.
+4. 선택된 카드를 확인한 뒤 canvas를 클릭하거나 x/y/z를 입력해 위치를 지정합니다.
+5. 필요하면 source 종류를 변경하거나 세부 값을 설정합니다.
    - `Tone`: 주파수와 위상을 갖는 합성 정현파
    - `Noise`: seed로 재현되는 white 또는 pink noise
    - `Audio asset`: 선택한 파일의 channel을 사용하며 짧은 파일은 반복 가능
-5. 필요하면 ambient 종류와 gain을 설정합니다.
-6. 검증 카드가 **저장 가능한 장면**이면 **Scene JSON 저장**을 누릅니다.
+6. 필요하면 ambient 종류와 gain을 설정합니다.
+7. 검증 카드가 **저장 가능한 장면**이면 **Scene JSON 저장**을 누릅니다.
+
+오디오 파일은 PCM WAV가 가장 안정적입니다. MP3, FLAC, OGG, M4A 등의 실제 decode 지원 여부는
+브라우저와 운영체제 codec에 따라 달라지며, 지원하지 않는 파일은 미리 듣기 시 오류로 표시됩니다.
 
 길이, sample rate, 음속, seed와 mix 정규화도 Scene JSON에 저장됩니다. 이미지가 있으면 표시
 평면의 x/y 범위, z와 image pixel 크기가 ground truth 좌표 변환에 사용됩니다.
@@ -40,7 +45,8 @@ id, 종류, 파일명과 SHA-256이 들어갑니다.
 
 - 파일 한 개는 최대 128 MiB, 연결 파일 합계는 최대 512 MiB입니다.
 - decode된 오디오의 합계는 최대 192 MiB입니다.
-- Scene을 다시 불러오면 브라우저 권한이 없으므로 원본 이미지와 오디오를 다시 선택해야 합니다.
+- Scene을 다시 불러오면 브라우저 권한이 없으므로 **원본 오디오 연결**에서 같은 오디오를 다시
+  선택해야 합니다. 이 동작은 새 source를 만들지 않고 manifest의 SHA-256으로 기존 asset을 연결합니다.
 - 같은 이름의 파일도 SHA-256이 manifest와 다르면 기존 asset으로 연결되지 않습니다.
 - 사용 중인 asset은 먼저 source, ambient 또는 image 참조를 바꾼 뒤 제거할 수 있습니다.