Agent skill

processing-audio

Converts and processes audio files using ffmpeg. Supports format conversion, sample rate changes, mono/stereo conversion, and segment splitting. Use for "오디오 변환", "wav 변환", "샘플레이트", "ffmpeg" requests.

View SKILL.md on GitHub Repository
Stars 10
Forks 1

Install this agent skill to your Project

npx add-skill https://github.com/jiunbae/agent-skills/tree/main/ml/audio-processor

SKILL.md

Audio Processor 스킬

Overview

ffmpeg을 활용한 오디오 파일 변환 및 처리 자동화 스킬입니다.

중요: 이 스킬이 활성화되면 Claude가 자동으로 스크립트를 실행합니다. 사용자가 직접 명령어를 입력할 필요가 없습니다.

핵심 기능:

  • 포맷 변환: wav, m4a, opus, mp3 등 상호 변환
  • 샘플레이트 변환: 8kHz, 16kHz, 22.05kHz, 44.1kHz, 48kHz
  • 채널 변환: 스테레오 → 모노, 모노 → 스테레오
  • 세그먼트 분할: 고정 시간 또는 타임스탬프 기반 분할
  • 배치 처리: 디렉토리 내 여러 파일 일괄 처리

Script Location

SCRIPT: ./scripts/audio-process.sh

Claude는 이 스크립트를 Bash 도구로 직접 실행합니다.

When to Use

이 스킬은 다음 상황에서 활성화됩니다:

명시적 요청:

  • "오디오 변환해줘", "wav로 바꿔줘"
  • "샘플레이트 16kHz로 변경해줘"
  • "모노로 변환해줘"
  • "10초 단위로 분할해줘"
  • "ffmpeg으로 처리해줘"

자동 활성화:

  • 오디오 파일 처리 요청 시 (.wav, .mp3, .m4a, .opus 등)
  • 음성 데이터 전처리 요청 시

Prerequisites

bash
# ffmpeg 설치 확인
ffmpeg -version

# 스크립트 실행 권한
chmod +x /path/to/agt/ml/audio-processor/scripts/audio-process.sh

Workflow

Claude 실행 절차

Step 1: 사용자 요청 분석

  • 입력 파일 경로 확인
  • 원하는 변환 유형 파악 (포맷/샘플레이트/채널/분할)
  • 출력 경로 결정 (명시되지 않으면 입력 파일과 같은 디렉토리)

Step 2: 스크립트 실행

bash
# 스크립트 경로
SCRIPT=./scripts/audio-process.sh

# 포맷 변환
$SCRIPT convert <input> <output> [--sr <rate>] [--mono|--stereo]

# 세그먼트 분할
$SCRIPT segment <input> <output_dir> --duration <sec>

# 배치 변환
$SCRIPT batch <input_dir> <output_dir> --format <fmt> [--sr <rate>] [--mono]

# 파일 정보 조회
$SCRIPT info <file>

Step 3: 결과 보고

  • 스크립트 출력을 사용자에게 전달
  • 변환 성공/실패 여부 확인

명령어 레퍼런스

작업 명령어
포맷 변환 $SCRIPT convert in.mp3 out.wav
16kHz mono 변환 $SCRIPT convert in.mp3 out.wav --sr 16000 --mono
8kHz 전화 품질 $SCRIPT convert in.mp3 out.wav --sr 8000 --mono
10초 분할 $SCRIPT segment in.wav segs/ --duration 10
배치 처리 $SCRIPT batch raw/ out/ --format wav --sr 16000 --mono
정보 조회 $SCRIPT info file.wav

자주 사용하는 변환 조합

용도 명령어
ML 학습용 (16kHz mono) audio-process.sh convert in.mp3 out.wav --sr 16000 --mono
전화 품질 (8kHz mono) audio-process.sh convert in.mp3 out.wav --sr 8000 --mono
고품질 (48kHz stereo) audio-process.sh convert in.mp3 out.wav --sr 48000
10초 청크 분할 audio-process.sh segment in.wav out/ --duration 10

Examples

예시 1: 기본 포맷 변환

사용자: test.mp3를 wav로 변환해줘

Claude: 오디오 변환을 수행합니다.

$ audio-process.sh convert test.mp3 test.wav

✅ 변환 완료
- 입력: test.mp3 (44.1kHz, stereo, 3:25)
- 출력: test.wav (44.1kHz, stereo, 3:25)

예시 2: ML 전처리 (16kHz mono)

사용자: 이 오디오 파일을 음성인식 모델용으로 변환해줘

Claude: ML 학습에 적합한 형식으로 변환합니다.

$ audio-process.sh convert input.m4a output.wav --sr 16000 --mono

✅ 변환 완료
- 입력: input.m4a (48kHz, stereo, 5:30)
- 출력: output.wav (16kHz, mono, 5:30)
- 파일 크기: 48MB → 10.5MB

예시 3: 세그먼트 분할

사용자: 긴 오디오를 10초 단위로 나눠줘

Claude: 10초 단위로 세그먼트를 분할합니다.

$ audio-process.sh segment long_audio.wav segments/ --duration 10

✅ 분할 완료
- 입력: long_audio.wav (2:30)
- 출력: 15개 세그먼트
  - segments/seg_000.wav (10s)
  - segments/seg_001.wav (10s)
  ...
  - segments/seg_014.wav (10s)

예시 4: 배치 처리

사용자: recordings 폴더의 모든 mp3를 16kHz mono wav로 변환해줘

Claude: 배치 변환을 수행합니다.

$ audio-process.sh batch recordings/ converted/ --format wav --sr 16000 --mono

✅ 배치 변환 완료
- 처리: 25개 파일
- 성공: 25개
- 출력 디렉토리: converted/

Configuration

기본값 설정

스크립트 상단에서 기본값 수정 가능:

bash
DEFAULT_SAMPLE_RATE=16000
DEFAULT_CHANNELS=1  # mono
DEFAULT_FORMAT="wav"
DEFAULT_SEGMENT_DURATION=10

출력 포맷별 권장 설정

포맷 코덱 품질 옵션
wav pcm_s16le (무손실)
mp3 libmp3lame -b:a 192k
opus libopus -b:a 128k
m4a aac -b:a 192k

Best Practices

DO:

  • 변환 전 info 명령으로 원본 파일 확인
  • ML용 오디오는 16kHz mono PCM 사용
  • 배치 처리 시 출력 디렉토리 미리 확인
  • 긴 파일 분할 시 적절한 세그먼트 길이 선택

DON'T:

  • 손실 포맷(mp3, opus)으로 여러 번 재인코딩
  • 업샘플링으로 품질 향상 기대 (8kHz → 48kHz)
  • 원본 파일 덮어쓰기 (항상 새 파일로 출력)

Troubleshooting

ffmpeg not found

bash
# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

코덱 지원 안됨

bash
# 지원 코덱 확인
ffmpeg -codecs | grep -i opus

# 코덱 설치 (Ubuntu)
sudo apt install libopus-dev

메모리 부족 (대용량 파일)

bash
# 스트리밍 모드 사용
audio-process.sh convert large.wav output.wav --streaming

Resources

파일 설명
scripts/audio-process.sh 오디오 처리 통합 스크립트

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

jiunbae/agent-skills

implementing-in-background

Orchestrates multiple AI agents (Claude, Codex, Gemini) for parallel implementation in the background. Separates independent tasks from planning docs, each agent writes code directly. Context-safe with auto-save. Use for "백그라운드 구현", "bg impl", "병렬 구현", "Codex로 구현", "구현해줘", "코드 작성해줘" requests.

10 1
Explore
jiunbae/agent-skills

review-fix-loop

Autonomous review-fix cycle that continuously reviews code using background-reviewer, fixes issues, and repeats until all findings are resolved. Use for "리뷰 루프", "자동 개선", "review fix loop", "리뷰 반복", "코드 개선 루프", "keep reviewing" requests.

10 1
Explore
jiunbae/agent-skills

planning-in-background

Orchestrates multiple AI agents (Claude, Codex, Gemini) for parallel planning in the background with auto-save. Agents continue running even when session hits context limits. Use for "백그라운드 기획", "bg plan", "병렬 기획", "멀티 AI 기획", "기획해줘", "N명이 기획", "계획", "플래닝", "plan", "설계" requests.

10 1
Explore
jiunbae/agent-skills

background-reviewer

Orchestrates multi-LLM parallel code review using Claude, Codex, and Gemini. Each agent reviews from a different perspective using agent personas (security, architecture, code quality, performance). Supports persona-based review via `agt persona review`. Use for "코드 리뷰", "리뷰해줘", "bg review", "멀티 리뷰", "background review", "페르소나 리뷰" requests.

10 1
Explore
jiunbae/agent-skills

managing-context

Discovers and loads relevant project context from markdown documentation before each task. Matches context documents based on keywords, file paths, and task types. Use at task start to access project plans, architecture, and implementation status.

10 1
Explore
jiunbae/agent-skills

indexing-static-context

Provides an index of global static context files in ~/.agents/. Returns appropriate static file paths for natural language queries like "내 정보", "보안 규칙". Use when other skills or agents need to locate reference information.

10 1
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results