Audion Python SDK

Repository: https://github.com/holamago/audion-python-sdk

목차

• 특징
• 요구사항
• 설치
• 빠른 시작
• API 문서
• 지원 파일 형식
• 문서
• 라이선스
• 지원
• 버전 히스토리

특징

• 간편한 음성 AI 통합: 몇 줄의 코드로 강력한 음성 AI 기능을 애플리케이션에 추가
• 다양한 입력 지원: 로컬 파일 및 URL을 통한 음성/비디오 처리
• 광범위한 파일 형식: 주요 오디오 및 비디오 형식 지원
• 유연한 Flow 시스템: 다양한 음성 AI 워크플로우 지원
• 간단한 API: 직관적이고 사용하기 쉬운 Python 인터페이스

요구사항

• Python 3.10+
• API 키 (Audion 서비스 등록 필요)
  • 회원가입 후 API Key 발급 받아야 합니다.

설치

pip을 사용하여 설치:

pip install audion-sdk

또는 개발용으로 레포를 클론하여 editable 모드로 설치:

git clone https://github.com/holamago/audion-python-sdk.git
cd audion-python-sdk

python -m venv venv
source venv/bin/activate

pip install -e .

빠른 시작

1. 클라이언트 초기화

from audion import AudionClient

# API 키로 클라이언트 초기화
client = AudionClient(api_key="your-api-key-here")

2. 로컬 파일 처리

• 오디오/비디오 업로드

# 로컬 오디오/비디오 파일 처리
result = client.flow(
    flow="audion_vu",
    input_type="file",
    input="path/to/your/audio.wav"
)
print(result)

3. URL 처리

# YouTube URL 처리
result = client.flow(
    flow="audion_vu",
    input_type="url",
    input="https://youtu.be/your-video-id"
)
print(result)

4. 자막 다운로드

# 로컬 파일을 처리하고 SRT 자막 파일로 다운로드
saved_path = client.download(
    input_type="file",
    input="path/to/your/audio.wav",
    format="srt"
)
print(f"저장 경로: {saved_path}")

# URL을 처리하고 SRT 자막 파일로 다운로드 (저장 경로 지정)
saved_path = client.download(
    input_type="url",
    input="https://youtu.be/your-video-id",
    format="srt",
    output_path="./output/subtitle.srt"
)
print(f"저장 경로: {saved_path}")

5. 진행률 확인

on_progress 콜백을 전달하면 Flow 실행 중 진행 이벤트를 받을 수 있습니다. 콜백을 사용해도 flow()의 최종 반환값은 기존과 동일한 JSON dict입니다.

def handle_progress(event):
    status = event.get("status")
    data = event.get("data", {})

    if status == "running":
        print(
            data.get("message"),
            data.get("percentage"),
            data.get("flowName"),
        )
    elif status == "completed":
        print("처리 완료")
    elif status == "failed":
        print("처리 실패:", data)

result = client.flow(
    flow="audion_vu",
    input_type="url",
    input="https://youtu.be/your-video-id",
    on_progress=handle_progress,
)

print(result)

진행 이벤트는 서버의 SSE(Server-Sent Events)를 SDK가 내부에서 구독해 콜백으로 전달합니다. 일반적인 이벤트 형태는 다음과 같습니다.

{
    "status": "running",
    "data": {
        "flowName": "speech2text",
        "progress": 50,
        "percentage": "50%",
        "currentStep": "Step 3/6: speech2text",
        "message": "Processing: speech2text (50%)",
    },
}

API 문서

AudionClient

Audion 서비스의 메인 클라이언트 클래스입니다.

초기화

AudionClient(
    api_key: str,           # 필수: API 인증 키
    base_url: str = None,   # 선택: 서버 기본 URL
    timeout: float = 300    # 선택: 요청 타임아웃 (초)
)

매개변수:

• api_key (str, 필수): Audion 서비스 인증을 위한 API 키
• base_url (str, 선택): 서버의 기본 URL. 기본값은 프로덕션 서버
• timeout (float, 선택): HTTP 요청 타임아웃. 기본값은 300초

예외:

• ValueError: api_key가 제공되지 않은 경우

메서드

flow(flow, input_type, input, on_progress=None, num_speakers=None)

지정된 플로우로 음성/비디오 처리를 실행합니다.

client.flow(
    flow: str,              # 실행할 플로우 이름
    input_type: str,        # 입력 타입: "file" 또는 "url"
    input: str,             # 파일 경로 또는 URL
    on_progress: callable = None,
    num_speakers: int = None # 화자 수 제한: 생략 또는 0은 제한 없음, 1~8은 지정 화자 수
)

매개변수:

• flow (str): 실행할 플로우의 이름
  • 현재 지원하는 플로우:
    • audion_vu: Voice Understanding
    • audion_vh: Voice Highlight
    • audion_stt: STT + LLM
  • Custom Flow 지원 가능 (email:contact@holamago.com)
• input_type (str): 입력 타입. "file" 또는 "url"
• input (str): 처리할 파일의 경로 또는 URL
• on_progress (callable, 선택): 진행률 이벤트를 받을 콜백. 지정하지 않으면 기존과 동일하게 최종 JSON 응답만 반환합니다.
• num_speakers (int, 선택): audion_stt 화자 수 제한. 생략 또는 0은 제한 없음, 1~8은 지정 화자 수로 처리합니다.

화자 수 지정 예시:

result = client.flow(
    flow="audion_stt",
    input_type="file",
    input="/path/to/audio.wav",
    num_speakers=2,
)

진행률 콜백 예시:

def handle_progress(event):
    status = event.get("status")
    data = event.get("data", {})

    if status == "running":
        print(data.get("currentStep"), data.get("percentage"))
    elif status == "completed":
        print("Flow completed")
    elif status == "failed":
        print("Flow failed", data)

result = client.flow(
    flow="audion_vu",
    input_type="url",
    input="https://youtu.be/your-video-id",
    on_progress=handle_progress,
)
print(result)

on_progress를 지정하면 SDK는 먼저 스트리밍 모드로 Flow를 시작하고, 반환된 documentId로 진행률 스트림을 구독합니다. running 이벤트는 콜백으로 계속 전달되고, 마지막 completed 이벤트의 결과가 기존 flow() 응답 형태로 반환됩니다.

반환값:

• dict: 처리 결과를 포함하는 JSON 응답

응답의 분석 결과는 result["content"]["output"]에 있습니다. Flow에 따라 일부 필드는 제공되지 않을 수 있습니다.

output = result["content"]["output"]

for utterance in output.get("utterances", []):
    biomarkers = (
        utterance.get("emotion_info", {})
        .get("principal_vocal_biomarkers", {})
    )
    f0_mean = biomarkers.get("pitch", {}).get("f0_mean")
    if f0_mean:
        print(f0_mean["value"], f0_mean["level"])

principal_vocal_biomarkers는 energy, pitch, shimmer, hnr, speech_related 등의 동적 카테고리로 구성됩니다. 각 지표는 {"value": ..., "level": ...} 형태이며, 신규 카테고리나 지표가 추가될 수 있습니다. words, emotion_info, speed_info, dementia_info, depression_info는 flow에 따라 없을 수 있으므로 .get()으로 접근하세요. 특히 audion_stt는 STT와 MLLM만 수행하므로 음성 바이오마커 및 인지/우울 분석 필드를 제공하지 않을 수 있습니다.

예외:

• ValueError: 지원하지 않는 input_type인 경우
• Exception: API 호출 실패 시

download(input_type, input, format, output_path)

오디오/비디오를 처리하고 자막 파일(SRT/VTT)을 다운로드합니다. 내부적으로 audion_vu 플로우를 실행한 뒤 결과를 자막 파일로 저장합니다.

client.download(
    input_type: str,        # 입력 타입: "file" 또는 "url"
    input: str,             # 파일 경로 또는 URL
    format: str = "srt",    # 자막 포맷: "srt" 또는 "vtt"
    output_path: str = None # 저장 경로 (선택)
)

매개변수:

• input_type (str): 입력 타입. "file" 또는 "url"
• input (str): 처리할 파일의 경로 또는 URL
• format (str, 선택): 다운로드할 자막 포맷. "srt" 또는 "vtt". 기본값은 "srt"
• output_path (str, 선택): 파일 저장 경로
  • None인 경우: 현재 디렉토리에 {원본파일명}_{documentId}.{format}으로 저장
  • 디렉토리 경로인 경우: 해당 디렉토리에 {원본파일명}_{documentId}.{format}으로 저장
  • 파일 경로인 경우: 지정된 경로에 저장

반환값:

• str: 저장된 파일의 절대 경로

예외:

• ValueError: 지원하지 않는 format이거나 서버 응답에서 documentId를 추출할 수 없는 경우
• Exception: API 호출 또는 파일 다운로드 실패 시

지원 파일 형식

오디오 형식

• .wav - WAV (Waveform Audio File Format)
• .mp3 - MP3 (MPEG-1 Audio Layer III)
• .m4a - M4A (MPEG-4 Audio)
• .ogg - OGG (Ogg Vorbis)
• .flac - FLAC (Free Lossless Audio Codec)
• .aac - AAC (Advanced Audio Coding)
• .wma - WMA (Windows Media Audio)
• .m4b, .m4p, .m4r, .m4v - 기타 MPEG-4 오디오 형식

비디오 형식

• .mp4 - MP4 (MPEG-4 Part 14)
• .mov - MOV (QuickTime File Format)
• .avi - AVI (Audio Video Interleave)
• .mkv - MKV (Matroska Video)
• .webm - WebM
• .wmv - WMV (Windows Media Video)
• .flv - FLV (Flash Video)
• .mpeg, .mpg - MPEG (Moving Picture Experts Group)

지원하는 Flow

• audion_vu: Voice Understanding - 음성 인식 및 분석
• audion_vh: Voice Highlight - 주요 음성 구간 추출
• audion_stt: STT + LLM - 음성 인식 및 언어 분석 (num_speakers 선택 지원)
• Custom Flow도 지원 가능합니다 (contact@holamago.com)

문서

• GitHub: github.com/holamago/audion-python-sdk
• 예제: examples/ 디렉토리

라이선스

이 프로젝트는 Apache License 2.0 하에 라이선스됩니다.

지원

• 문서: Audion 공식 문서
• 이슈: GitHub Issues
• 이메일: contact@holamago.com

버전 히스토리

v0.2.1

• audion_stt flow의 num_speakers 선택 옵션 지원
• num_speakers 생략 또는 0 지정 시 화자 수 제한 없음 처리

v0.2.0

• 중첩형 principal_vocal_biomarkers 응답 스키마 문서화
• 발화별 words, 치매/우울 분석의 best 값 반영
• audion_stt flow 지원

v0.1.7

• output_path에 존재하지 않는 디렉토리 경로 지정 시 자동 생성 처리 개선
• 다운로드 파일명에 원본 파일명 포함 ({원본파일명}_{documentId}.{format})
• flow 응답 구조(content.documentId) 대응 수정
• URL 입력 검증 추가
• 자막 다운로드 기능 추가 (download 메서드)
• SRT/VTT 포맷 자막 파일 다운로드 지원
• 자막 다운로드 예제 추가

v0.1.2

• PyPI 패키지 구성 정리 (pyproject.toml 기반 빌드)
• SDK 내부 구조 정리 (로그 유틸과 코어/헬퍼 모듈 리팩토링)
• 문서 개선 (README 정리 및 예제 링크 정리)

v0.1.0

• 초기 릴리스
• 기본 flow API 지원
• 파일 및 URL 입력 지원
• 다중 오디오/비디오 형식 지원