FS 경로 규약 — dataset_variants ↔ 디렉토리 매핑

fs_walker / harness xdata fs-sync 의 행동 정본. 본 문서가 명시하지 않은 토큰/패턴은 자동 등록하지 않고 pending 으로 보류해 작업자 판단을 받는다.

1. 스코프

• 현 walker plugin 3 종 (tools/xdata/walkers/):
  • xvoice3_main — KOR/MAIN/{gender}/{speaker_key}/base_phnseq/... (본 문서 §2 정본) + KOR/PERSONAL/{cat}/{speaker_key}/base_phnseq/... (§2.1 PERSONAL 분기, D-viii). NFS root + 162 로컬 사본 (xvoice3_main_local) 듀얼 source 사용 가능.
  • aihub_emotion — AI_HUB_DATA/015.emotion_style00/{1.Training|2.Validation}/source/{category}/{leaf}/{speaker_code}/ (별 규약, walker 본체 정본).
  • en_us_main — EN_US/{service}/{gender}/{speaker_key}/base_phnseq/... (service ∈ {HIFI, LIBRI, MAIN, ORIGINAL} 4종). xvoice3_main 와 디렉토리 컨벤션 동일하지만 walker 단위 분리 (audit sync_run.sources_summary source 별 카운트 + metadata.sources[].root lang prefix 분리). utterance_style enum (KNOWN/EXPERIMENTAL) + phoneme_source 정규식은 xvoice3_main 에서 import 해서 정본 1 곳 유지 (디렉토리 컨벤션 동일).
• 후속 walker 큐 (plan docs/governance/plans/2026-05-15-xdata-next-tracks.md §9.3 묶음 D):
  • D-iv AI_HUB 133.emotion_style + sbert (/HDD0/TRAIN_DATA_S98_01/AI_HUB_DATA/133.emotion_style/training_data/FEMALE_EACH 기반의 /HDD1/raymond/data/AI_hub_emo_yoursbert).
  • D-ix base_phnseq/manual/... 비표준 leaf 패턴.
  • D-x 외부 데이터 walker — EN_US/PERSONAL/LJSpeech-1.1/..., KOR/PERSONAL/{audio_book,celebrity,character,jj_mbc,robot_*,tmap,voiceapplication,auto_train_selvas,2025_tmp}/... 등 외부 산 데이터셋. en_us_main / xvoice3_main scope 밖이라 unsupported_service 또는 unsupported_personal_category pending 으로 분리됨. LJSpeech 는 4 service 컨벤션 (HIFI/LIBRI/MAIN/ORIGINAL) 과 layout 자체가 다르므로 별 walker 신규.

2. 구조 (R1)

{storage_root}/{lang}/{service}/{gender}/{speaker_key}/base_phnseq/
  {phoneme_source}_xvoice{phoneme_source_version}/
    {utterance_style}[_{v1}[_{v2}...]]/

• lang ∈ {KOR} (스코프 내).
• service ∈ {MAIN, PERSONAL} — MAIN 은 본 절 그대로, PERSONAL 은 §2.1 분기 (gender 층 없음 + service_category MAIN alias).
• gender ∈ {female, male} (MAIN 분기 한정 — PERSONAL 분기는 gender 층 부재).
• speaker_key — ADR 0004, 불변. 디렉토리명 그대로 사용.
• base_phnseq — 고정 문자열. 없으면 해당 speaker 는 pending.
• phoneme_source + version — 디렉토리명 ^(.+?)_xvoice(\d+(?:\.\d+)?)$ 정규식 매칭. 예: manual_xvoice3.1 → source=manual, version=xvoice3.1.
• utterance_style — 마지막 디렉토리의 첫 세그먼트. §3 의 허용 집합에 속해야 한다.
• v1 ... vN — 축 값 토큰. §5 규약.

2.1 PERSONAL 분기 (D-viii, 2026-05-21)

{storage_root}/KOR/PERSONAL/{category}/{speaker_key}/base_phnseq/... — gender 층이 없는 별도 분기. PERSONAL 은 audio source vintage 분리축이 아니라 사업적 분류축이므로 walker 가 service_category="MAIN" 으로 alias normalize 한다 (natural_key 5 축 = speaker_key/lang/style/phoneme_source/variation 에 service_category 미포함 — ADR-0012 정합, supersedes ADR-0007). gender 는 PERSONAL 트리에 디렉토리 층이 없으니 None emit, 운영자가 NocoDB 뷰어에서 수동 부여하고 xvoice3 fs-sync preservation 정책으로 보존된다 (feedback_user_approval_before_writes.md + project_operator_curated_fields.md hybrid 모델).

162 mirror (/HDD1/raymond/data/KOR/MAIN/{gender}/{spk}) 는 manual phoneme_source

• gender 디렉토리 명시본이고, NFS PERSONAL (예: audiro/pej/base_phnseq/ip_info2_xvoice3.1) 은 ip_info* phoneme_source 가 별도 vintage 라 동일 화자라도 natural_key 충돌하지 않는다 — PV 동거 (_pv_key=(version_key, service_category)) + _merge_variant dst-precedence + WARN 정책으로 처리.

3. natural_key 매핑 (ADR 0012, supersedes ADR 0007)

natural_key = "{speaker_key}/{lang}/{utterance_style}/{phoneme_source}/{variation}"

허용 utterance_style (1차 스코프, 정규):

Compound utterance_style (R5: 2-토큰 leaf 묶음 매칭. preprocessing axes 가 아닌 utterance_style 의 sub-enum 으로 처리 — 정규 학습 데이터라 experimental=true 자동 부여 회피):

walker (_parse_style_dir) 는 leaf 의 첫 두 토큰 합본이 KNOWN compound 에 있으면 compound style 로 묶고 나머지를 preprocessing axes 로 분리한다. 예:

• pat1_syll_16k → style=pat1_syll, axes=[16k] (sample_rate=16k experimental)
• pat1_reduce_brth → compound (pat1_reduce) KNOWN 아님 → style=pat1, axes=[reduce, brth]

실험용 utterance_style (leaf 전체가 정확히 매칭되면 axes 분리 없이 통째로 채택, processed_version.experimental=true):

정규 enum / 실험 enum / compound 어디에도 없는 값은 pending(unknown_utterance_style). 정본은 tools/xdata/walkers/xvoice3_main.py:KNOWN_UTTERANCE_STYLES 와 EXPERIMENTAL_UTTERANCE_STYLES — en_us_main 도 같은 enum 을 import 한다.

4. processed_version 매핑

utterance_style 뒤 토큰들은 하나의 processed_version 을 구성:

processed_version:
  phoneme_encoding: <§5 참조>
  phoneme_source_version: "xvoice3.1"     # 디렉토리에서 추출
  preprocessing:
    breath: vanilla | reduce_brth | rm_brth
    trim: vanilla | trimIP | trim
    sample_rate: native | 16k
    sbert: vanilla | sbert
    perturbation: vanilla | perturb
  data_source: internal | internal_processed   # 조합에서 도출 (phase2 §16-A.3 A안)
  mfa_set: null        # 본 경로 규약 범위 밖 — 수작업 메타
  mfa_tnqst: false     # 본 경로 규약 범위 밖 — 수작업 메타
  paths: {nfs_train: "<nfs_abs_path>", server_162: "<162_local_abs_path>"}
  service_category: MAIN | ORIGINAL | HIFI | LIBRI | ...   # audio source 분리축 (ADR-0007 L42)
  updated_at: <mtime>

paths 키 의미 (server_tag 정본, 2026-05-19 정정): nfs_train = NFS 마운트 절대 경로 (예: /HDD0/TRAIN_DATA_S98_01/...), server_162 = 162 서버 로컬 사본 (예: /HDD1/raymond/data/...). multi-source 모델에서 한 natural_key 의 같은 version_key PV 가 양쪽에 있으면 paths 두 키 모두 채워진다 (_apply_existing_preservation + _merge_variant cross-source pv.paths union). 단일 키 PV = 한쪽 디스크에만 존재.

5. 디렉토리 suffix 네이밍 규약 (정본 — R1~R8)

워커(전처리 파이프라인) 는 본 절을 강제 준수한다. 위반 시 fs-sync 가 pending 버킷으로 분리하여 레지스트리 진입을 차단한다.

R1. 구조

{utterance_style}[_{v1}[_{v2}...]]

첫 세그먼트는 utterance_style, 이후는 축 값 (value-only, axis 이름 미노출).

R2. value 전역 unique

한 값은 정확히 한 축에만 속한다. 축 판별은 전역 token 레지스트리 tools/xdata/preprocessing.py 의 PREPROC_TOKEN_MAP + PHONEME_ENCODING_TOKENS 조회로 수행. 신규 값 도입 시 (a) 본 문서 R5 표 (b) 레지스트리를 동시 PR 로 추가한다.

R3. 토큰 순서 (고정, 생성 측 의무)

breath → trim → sample_rate → phoneme_encoding → sbert → perturbation

파서는 순서 무관 매칭이나, 전처리 파이프라인은 위 순서로 디렉토리명을 생성한다 (사람이 읽을 때 일관성 + 충돌 조기 감지).

R4. 기본값 생략

축 기본값(vanilla/native/full)은 경로에 쓰지 않는다.

• breath=vanilla & trim=vanilla & sample_rate=native & sbert=vanilla & perturbation=vanilla & subset=full & phoneme_encoding=null → 디렉토리명 = common (단독). phoneme_encoding 은 ADR-0011 정합 — null 이 기본.

R5. 허용 token 표 (초기 세트)

preprocessing 축

실험(●) 축 = ADR 0008 에 정의된 EXPERIMENTAL_AXES(subset, sample_rate, perturbation, experiment_tag). 해당 축에 기본값이 아닌 토큰이 있으면 processed_version.experimental = true 로 기록되고 기본 export 에서 자동 제외된다 (§5 R8).

phoneme_encoding (processed_version 직속)

ADR-0011 정합 enum = null (기본, 토큰 미박음) / "hts" / "hts_ipa" (lang-agnostic). ko_base / ko_ipa / en_ipa 는 ADR-0010 잔재로 폐기 (실 디스크 0건 확인 후 정리).

R6. 불법 패턴 예

참고: common_torchmel, common_16000, common_perturb_ipa 는 등록되어 있어 accepted (실험 pv 로 분류) — 미등록 token 예시로는 부적합.

R7. 준수 검증

1. 1차(자동 감시): fs-sync 실행 시 위반 variant 는 pending 리포트로 통지 — pending_<ts>.json.
2. 후속(선제 차단): scripts/lint_fs_paths.py (전처리 PR CI) — 신규 경로를 PR 단계에서 검증. 구현 시점은 운영 경험 축적 후 판단.

R8. 실험 축 / processed_version.experimental

• EXPERIMENTAL_AXES = (subset, sample_rate, perturbation, experiment_tag) 중 한 축이라도 기본값이 아니면 해당 processed_version 은 experimental=true 로 기록된다 (정본: tools/xdata/preprocessing.py:is_experimental).
• 또한 §3 의 실험용 utterance_style (novel_*, pat_16k, emotion 라벨 등) 로 매칭된 디렉토리는 자동으로 experimental=true (fs_walker._parse_style_dir 의 EXPERIMENTAL_UTTERANCE_STYLES 분기).
• 실험 pv 는 동일 natural_key 아래 vanilla pv 와 공존한다. version_key 가 실험 축(subset/experiment_tag) 을 포함하므로 해시 충돌 없이 별도 레코드로 저장.
• export 필터: variant.inclusion_policy != 'excluded' AND pv.experimental == false (ADR 0008). 실험 pv 는 별도 요청 없이는 기본 훈련셋에 편입되지 않음.
• 신규 실험 토큰 추가 시 §5.5 R5 표 + PREPROC_TOKEN_MAP / REGEX_TOKEN_MATCHERS / EXPERIMENTAL_AXES 동시 갱신 (§7 워크플로우 참조). 새 utterance_style 실험 그룹은 EXPERIMENTAL_UTTERANCE_STYLES 갱신.
• vad/vad2_1 은 experiment_tag 축의 실험 값으로 정합 (PR-B). 운영자가 inclusion_policy 까지 자동 부여하지 않는다 — experimental=true 만 walker emit, inclusion_policy=excluded 는 운영자가 NocoDB 에서 일괄 patch (ADR 0008: inclusion_policy 결정 책임 = 운영자).

6. fallback / skip 규약

큐 상세 — plan docs/governance/plans/2026-05-15-xdata-next-tracks.md §9.3 묶음 D.

7. 신규 축/값 추가 워크플로우 (Q19)

새 전처리 단계가 디렉토리 suffix 로 노출될 때 따르는 절차:

1. spec 갱신 PR — 본 문서 R5 표에 값 + 의미 추가.
2. 레지스트리 갱신 — 같은 PR 에서 tools/xdata/preprocessing.py 의 PREPROC_TOKEN_MAP 또는 PHONEME_ENCODING_TOKENS 확장.
3. 축 신규 도입 시 — DEFAULT_PREPROCESSING 확장 + ADR 0012 추가 PR (스키마 변경이므로 별 ADR 필요).
4. 검증 — harness xdata fs-sync --dry-run 에서 관련 pending 이 added/modified 로 승격되는지 확인.

참조

• ADR 0012 — docs/decisions/0012-variation-paradigm.md (supersedes ADR 0007)
• ADR 0008 — docs/decisions/0008-variant-inclusion-and-notes.md
• plan — docs/superpowers/plans/2026-04-24-fs-walker-registry-sync.md
• 기존 CLI 가이드 — xdata-guide.md