aup-parser

aup-parser is an Audacity .aup3 parser package with a Rust core and typed Python interface.

Highlights

• Rust core for binary XML and sampleblocks analysis
• Class-based Python API (AUPParser) with TypedDict return types
• Optional audio export helper

Package Layout

• src/: Rust core (PyO3 extension)
• python/aup_parser/: Python API, types, exports
• tests/: API/parity tests and golden fixtures

Build (local dev)

cd /Users/joonholee/deeply/aup3-parser
python3 -m pip install --user --break-system-packages maturin
python3 -m maturin build --release -i python3
python3 -m pip install --user --break-system-packages --force-reinstall target/wheels/aup_parser-*.whl

Python API (Class-only)

from aup_parser import AUPParser

parser = AUPParser("tests/test.aup3")
parsed = parser.parse()
raw = parser.inspect_core(profile="full")  # low-level diagnostics payload

AUPParser.parse() signature:

def parse(
    self,
    *,
    audio_output_path: str | pathlib.Path | None = None,
) -> ParseResultTD: ...

• audio_output_path: None이 아니면 WAV를 export
  • 싱글 채널 프로젝트: audio_output_path를 항상 폴더로 취급하고, 내부에 WAV 1개 생성
  • 싱글 채널 파일명은 원본 오디오 이름(가능하면) 기반으로 결정
  • 멀티 채널 프로젝트: audio_output_path를 폴더로 사용하여 채널별 WAV 파일 생성
  • 멀티 채널 + 파일처럼 보이는 경로(out.wav) 입력 시: 자동으로 out_channels/ 폴더로 정규화
  • 파일명은 항상 track_name 기반으로 생성(트랙명이 없으면 channel_XX)
  • 동일한 트랙명이 여러 개면 _1, _2 suffix를 붙여 충돌 방지
  • 샘플레이트는 wavetrack.rate 우선, 없으면 프로젝트 sample_rate를 사용
  • 타임라인 복원: clip metadata(offset, trimLeft, trimRight)를 우선 적용하고, 불가능한 경우 waveblock.start 기준으로 배치
  • gap 구간은 zero-fill, 겹침 구간은 later block overwrite 규칙 사용

Parse Result

parse()는 항상 full 형식(diagnostics 포함)을 반환합니다:

{
  "schema_version": "2",
  "project": {...},
  "audio": {...},
  "diagnostics": {...},
  "exports": {...}  # optional
}

project fields

original_audio_file_name 주의:

• Audacity .aup3는 원본 입력 파일명을 항상 보존하지 않습니다.
• 따라서 확정값이 아닐 수 있으며, 추정 출처는 original_audio_file_name_source로 확인하세요.

audio fields

audio.sample_format

audio.tracks[] (TrackSummaryTD)

audio.clips[] (ClipSummaryTD)

audio.timeline (TimelineSummaryTD)

diagnostics fields

Exports fields

exports.audio_output 필드:

inspect_core() (Raw)

inspect_core()는 low-level payload를 그대로 반환합니다.

• 용도: 디버깅, parity 검증, 내부 분석
• 안정 API 용도는 parse() 사용 권장

Compatibility Notes

• Python 3.11~3.14
• abi3-py311 build strategy
• CI validates install + runtime parse on all combinations:
  • Linux/macOS/Windows
  • Python 3.11, 3.12, 3.13, 3.14
• Release wheels are built for:
  • Linux (ubuntu-latest)
  • Windows (windows-latest)
  • macOS Apple Silicon (macos-15)
  • macOS Intel (macos-15-intel)
• If a wheel is unavailable for your environment, pip falls back to sdist build and requires a Rust toolchain.

Release

GitHub Actions workflow (.github/workflows/release.yml) runs:

1. Matrix tests on PRs
2. Wheel/sdist build on version tags (v*)
3. Publish dist/* to GitHub Release assets
4. Publish dist/* to GitHub Packages (GHCR OCI artifact)
5. Optional PyPI publish (only when UV_PUBLISH_TOKEN secret is set)

PyPI Token Setup

1. Create a PyPI API token (__token__) on PyPI account settings.
2. In GitHub repo settings, add:
   • Settings > Secrets and variables > Actions > New repository secret
   • Name: UV_PUBLISH_TOKEN
   • Value: pypi-... token string
3. Push a release tag (vX.Y.Z). The publish-pypi job uploads dist/* via:
   • uv publish --trusted-publishing never dist/*

GitHub Distribution

• Release assets: https://github.com/<owner>/<repo>/releases/tag/vX.Y.Z
• GitHub Packages (GHCR): ghcr.io/<owner>/aup-parser:vX.Y.Z and ghcr.io/<owner>/aup-parser:X.Y.Z
• GHCR pull example:
  • oras pull ghcr.io/<owner>/aup-parser:vX.Y.Z
  • pulled wheel/sdist files can then be installed with pip install <wheel-file>