목적
이 스킬은 오디오-텍스트 변환을 자동화하여 전문 Markdown 출력을 생성하고, 풍부한 기술 메타데이터(화자, 타임스탬프, 언어, 파일 크기, 길이)를 추출하며, 구조화된 회의록 및 경영진 요약을 생성합니다. Faster-Whisper 또는 Whisper를 설정 없이 사용하며, 하드코딩된 경로나 API 키 없이 프로젝트 전반에서 작동합니다.
Plaid와 같은 도구에서 영감을 받아, 이 스킬은 원시 오디오 녹음을 실행 가능한 문서로 변환하여 회의, 인터뷰, 강의, 콘텐츠 분석에 이상적입니다.
사용 시기
다음과 같은 경우 이 스킬을 호출하세요:
- 사용자가 오디오/비디오 파일을 텍스트로 변환해야 하는 경우
- 사용자가 녹음으로부터 회의록을 자동 생성하려는 경우
- 사용자가 대화에서 화자 식별(화자 분리)을 필요로 하는 경우
- 사용자가 자막(SRT, VTT 형식)을 필요로 하는 경우
- 사용자가 긴 오디오 콘텐츠의 경영진 요약을 원하는 경우
- 사용자가 "이 오디오를 텍스트로 변환해줘", "녹음 파일을 텍스트로 바꿔줘", "회의록을 생성해줘" 등의 변형된 요청을 하는 경우
- 사용자가 일반적인 형식(MP3, WAV, M4A, OGG, FLAC, WEBM)의 오디오 파일을 가지고 있는 경우
워크플로우
단계 0: 검색 (자동 변환 도구 감지)
목표: 사용자 설정 없이 사용 가능한 변환 엔진을 식별합니다.
작업:
감지 명령을 실행하여 설치된 도구를 확인합니다:
# Faster-Whisper 확인 (선호 - 4-5배 빠름)
if python3 -c "import faster_whisper" 2>/dev/null; then
TRANSCRIBER="faster-whisper"
echo "✅ Faster-Whisper 감지됨 (최적화됨)"
# 대체: 원본 Whisper
elif python3 -c "import whisper" 2>/dev/null; then
TRANSCRIBER="whisper"
echo "✅ OpenAI Whisper 감지됨"
else
TRANSCRIBER="none"
echo "⚠️ 변환 도구를 찾을 수 없음"
fi
# ffmpeg 확인 (오디오 형식 변환)
if command -v ffmpeg &>/dev/null; then
echo "✅ ffmpeg 사용 가능 (형식 변환 활성화됨)"
else
echo "ℹ️ ffmpeg를 찾을 수 없음 (제한된 형식 지원)"
fi
변환기를 찾을 수 없는 경우:
제공된 스크립트를 사용한 자동 설치를 제안합니다:
echo "⚠️ 변환 도구를 찾을 수 없음"
echo ""
echo "🔧 종속성을 자동 설치하시겠습니까? (권장)"
read -p "설치 스크립트를 실행하시겠습니까? [Y/n]: " AUTO_INSTALL
if [[ ! "$AUTO_INSTALL" =~ ^[Nn] ]]; then
# 스킬 디렉토리 가져오기 (리포지토리 및 심볼릭 링크 설치 모두 작동)
SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# 설치 스크립트 실행
if [[ -f "$SKILL_DIR/scripts/install-requirements.sh" ]]; then
bash "$SKILL_DIR/scripts/install-requirements.sh"
else
echo "❌ 설치 스크립트를 찾을 수 없음"
echo ""
echo "📦 수동 설치:"
echo " pip install faster-whisper # 권장"
echo " pip install openai-whisper # 대체"
echo " brew install ffmpeg # 선택 사항 (macOS)"
exit 1
fi
# 설치 성공 확인
if python3 -c "import faster_whisper" 2>/dev/null || python3 -c "import whisper" 2>/dev/null; then
echo "✅ 설치 성공! 변환을 진행합니다..."
else
echo "❌ 설치 실패. 수동으로 설치해주세요."
exit 1
fi
else
echo ""
echo "📦 수동 설치 필요:"
echo ""
echo "권장 (가장 빠름):"
echo " pip install faster-whisper"
echo ""
echo "대체 (원본):"
echo " pip install openai-whisper"
echo ""
echo "선택 사항 (형식 변환):"
echo " brew install ffmpeg # macOS"
echo " apt install ffmpeg # Linux"
echo ""
exit 1
fi
이렇게 하면 사용자가 한 번의 확인으로 종속성을 설치하거나, 원하는 경우 수동 설치를 선택할 수 있습니다.
변환기를 찾은 경우:
단계 0b(CLI 감지)로 진행합니다.
단계 1: 오디오 파일 검증
목표: 파일이 존재하는지 확인하고, 형식을 검사하며, 메타데이터를 추출합니다.
작업:
-
사용자로부터 파일 경로 또는 URL 수락:
- 로컬 파일:
meeting.mp3 - URL:
https://example.com/audio.mp3(임시 디렉토리에 다운로드)
- 로컬 파일:
-
파일 존재 확인:
if [[ ! -f "$AUDIO_FILE" ]]; then
echo "❌ 파일을 찾을 수 없음: $AUDIO_FILE"
exit 1
fi
- ffprobe 또는 파일 유틸리티를 사용하여 메타데이터 추출:
# 파일 크기 가져오기
FILE_SIZE=$(du -h "$AUDIO_FILE" | cut -f1)
# ffprobe를 사용하여 길이 및 형식 가져오기
DURATION=$(ffprobe -v error -show_entries format=duration \
-of default=noprint_wrappers=1:nokey=1 "$AUDIO_FILE" 2>/dev/null)
FORMAT=$(ffprobe -v error -select_streams a:0 -show_entries \
stream=codec_name -of default=noprint_wrappers=1:nokey=1 "$AUDIO_FILE" 2>/dev/null)
# 길이를 HH:MM:SS로 변환
DURATION_HMS=$(date -u -r "$DURATION" +%H:%M:%S 2>/dev/null || echo "알 수 없음")
- 파일 크기 확인 (클라우드 API의 경우 큰 파일 경고):
SIZE_MB=$(du -m "$AUDIO_FILE" | cut -f1)
if [[ $SIZE_MB -gt 25 ]]; then
echo "⚠️ 큰 파일 ($FILE_SIZE) - 처리에 몇 분 정도 걸릴 수 있음"
fi
- 형식 검증 (지원: MP3, WAV, M4A, OGG, FLAC, WEBM):
EXTENSION="${AUDIO_FILE##*.}"
SUPPORTED_FORMATS=("mp3" "wav" "m4a" "ogg" "flac" "webm" "mp4")
if [[ ! " ${SUPPORTED_FORMATS[@]} " =~ " ${EXTENSION,,} " ]]; then
echo "⚠️ 지원하지 않는 형식: $EXTENSION"
if command -v ffmpeg &>/dev/null; then
echo "🔄 WAV로 변환 중..."
ffmpeg -i "$AUDIO_FILE" -ar 16000 "${AUDIO_FILE%.*}.wav" -y
AUDIO_FILE="${AUDIO_FILE%.*}.wav"
else
echo "❌ 형식을 변환하려면 ffmpeg를 설치하세요: brew install ffmpeg"
exit 1
fi
fi
단계 3: Markdown 출력 생성
목표: 메타데이터, 변환 내용, 회의록, 요약이 포함된 구조화된 Markdown을 생성합니다.
출력 템플릿:
# 오디오 변환 보고서
## 📊 메타데이터
| 필드 | 값 |
|-------|-------|
| **파일 이름** | {filename} |
| **파일 크기** | {file_size} |
| **길이** | {duration_hms} |
| **언어** | {language} ({language_code}) |
| **처리 날짜** | {process_date} |
| **식별된 화자 수** | {num_speakers} |
| **변환 엔진** | {engine} (모델: {model}) |
## 📋 회의록
### 참가자
- {speaker_1}
- {speaker_2}
- ...
### 논의된 주제
1. **{topic_1}** ({timestamp})
- {key_point_1}
- {key_point_2}
2. **{topic_2}** ({timestamp})
- {key_point_1}
### 결정 사항
- ✅ {decision_1}
- ✅ {decision_2}
### 실행 항목
- [ ] **{action_1}** - 담당자: {speaker} - 마감일: {date_if_mentioned}
- [ ] **{action_2}** - 담당자: {speaker}
*오디오-변환기 스킬 v1.0.0 생성*
*변환 엔진: {engine} | 처리 시간: {elapsed_time}초*
구현:
지능형 요약을 위해 AI 모델(Claude/GPT)과 함께 Python 또는 bash 사용:
def generate_meeting_minutes(segments):
"""변환 내용에서 주제, 결정 사항, 실행 항목을 추출합니다."""
# 주제별로 세그먼트 그룹화 (타임스탬프 기준 간단한 클러스터링)
topics = cluster_by_topic(segments)
# 실행 항목 식별 (키워드: "해야 함", "할 것", "~할 필요가 있음", "action")
action_items = extract_action_items(segments)
# 결정 사항 식별 (키워드: "결정됨", "합의됨", "승인됨")
decisions = extract_decisions(segments)
return {
"topics": topics,
"decisions": decisions,
"action_items": action_items
}
def generate_summary(segments, max_paragraphs=5):
"""AI(API 또는 로컬 모델을 통한 Claude/GPT)를 사용하여 경영진 요약을 생성합니다."""
full_text = " ".join([s["text"] for s in segments])
# 밀집도 체인 접근 방식(프롬프트 엔지니어 프레임워크에서) 사용
summary_prompt = f"""
다음 변환 내용을 {max_paragraphs}개의 간결한 단락으로 요약하세요.
주요 주제, 결정 사항 및 실행 항목에 초점을 맞추세요.
변환 내용:
{full_text}
"""
# AI 모델 호출 (플레이스홀더 - 사용자가 Claude API를 통합하거나 로컬 모델을 사용할 수 있음)
summary = call_ai_model(summary_prompt)
return summary
출력 파일 명명:
# v1.1.0: 덮어쓰기를 방지하기 위해 타임스탬프 사용
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
TRANSCRIPT_FILE="transcript-${TIMESTAMP}.md"
ATA_FILE="ata-${TIMESTAMP}.md"
echo "$TRANSCRIPT_CONTENT" > "$TRANSCRIPT_FILE"
echo "✅ 변환 내용 저장됨: $TRANSCRIPT_FILE"
if [[ -n "$ATA_CONTENT" ]]; then
echo "$ATA_CONTENT" > "$ATA_FILE"
echo "✅ 회의록 저장됨: $ATA_FILE"
fi
시나리오 A: 사용자 정의 프롬프트 제공
워크플로우:
-
사용자의 프롬프트 표시:
📝 사용자가 제공한 프롬프트: ┌──────────────────────────────────┐ │ [사용자 프롬프트 미리보기] │ └──────────────────────────────────┘ -
프롬프트 엔지니어로 자동 개선 (사용 가능한 경우):
🔧 프롬프트 엔지니어로 프롬프트 개선 중... [호출: gh copilot -p "이 프롬프트를 개선: {user_prompt}"] -
두 버전 모두 표시:
✨ 개선된 버전: ┌──────────────────────────────────┐ │ 역할: 당신은 문서 작성자입니다... │ │ 지침: 다음을 변환... │ │ 단계: 1) ... 2) ... │ │ 최종 목표: ... │ └──────────────────────────────────┘ 📝 원본 버전: ┌──────────────────────────────────┐ │ [사용자의 원본 프롬프트] │ └──────────────────────────────────┘ -
사용할 버전 확인:
💡 개선된 버전을 사용하시겠습니까? [s/n] (기본값: s): -
선택한 프롬프트로 처리:
- "s"인 경우: 개선된 버전 사용
- "n"인 경우: 원본 사용
LLM 처리 (두 시나리오 모두)
프롬프트가 확정되면:
from rich.progress import Progress, SpinnerColumn, TextColumn
def process_with_llm(transcript, prompt, cli_tool='claude'):
full_prompt = f"{prompt}\n\n---\n\n변환 내용:\n\n{transcript}"
with Progress(
SpinnerColumn(),
TextColumn("[progress.description]{task.description}"),
transient=True
) as progress:
progress.add_task(
description=f"🤖 {cli_tool}로 처리 중...",
total=None
)
if cli_tool == 'claude':
result = subprocess.run(
['claude', '-'],
input=full_prompt,
capture_output=True,
text=True,
timeout=300 # 5분
)
elif cli_tool == 'gh-copilot':
result = subprocess.run(
['gh', 'copilot', 'suggest', '-t', 'shell', full_prompt],
capture_output=True,
text=True,
timeout=300
)
if result.returncode == 0:
return result.stdout.strip()
else:
return None
진행 상황 출력:
🤖 claude로 처리 중... ⠋
[완료 후:]
✅ 회의록이 성공적으로 생성되었습니다!
최종 출력
성공 (두 파일 모두):
💾 파일 저장 중...
✅ 생성된 파일:
- transcript-20260203-023045.md (순수 변환 내용)
- ata-20260203-023045.md (LLM으로 처리됨)
🧹 임시 파일 제거됨: metadata.json, transcription.json
✅ 완료! 총 시간: 3분 45초
변환 내용만 (사용자가 LLM 거부):
💾 파일 저장 중...
✅ 생성된 파일:
- transcript-20260203-023045.md
ℹ️ 회의록이 생성되지 않음 (LLM 처리가 사용자에 의해 거부됨)
🧹 임시 파일 제거됨: metadata.json, transcription.json
✅ 완료!
단계 5: 결과 요약 표시
목표: 완료 상태 및 다음 단계를 표시합니다.
출력:
echo ""
echo "✅ 변환 완료!"
echo ""
echo "📊 결과:"
echo " 파일: $OUTPUT_FILE"
echo " 언어: $LANGUAGE"
echo " 길이: $DURATION_HMS"
echo " 화자: $NUM_SPEAKERS"
echo " 단어 수: $WORD_COUNT"
echo " 처리 시간: ${ELAPSED_TIME}초"
echo ""
echo "📝 생성됨:"
echo " - $OUTPUT_FILE (Markdown 보고서)"
[대체 형식인 경우:]
echo " - ${OUTPUT_FILE%.*}.srt (자막)"
echo " - ${OUTPUT_FILE%.*}.json (구조화된 데이터)"
echo ""
echo "🎯 다음 단계:"
echo " 1. 회의록 및 실행 항목 검토"
echo " 2. 참가자와 보고서 공유"
echo " 3. 실행 항목 추적 및 완료"
사용 예시
예시 1: 기본 변환
사용자 입력:
copilot> 오디오를 Markdown으로 변환: meeting-2026-02-02.mp3
스킬 출력:
✅ Faster-Whisper 감지됨 (최적화됨)
✅ ffmpeg 사용 가능 (형식 변환 활성화됨)
📂 파일: meeting-2026-02-02.mp3
📊 크기: 12.3 MB
⏱️ 길이: 00:45:32
🎙️ 처리 중...
[████████████████████] 100%
✅ 언어 감지됨: 한국어 (ko-KR)
👥 식별된 화자: 4
📝 Markdown 출력 생성 중...
✅ 변환 완료!
📊 결과:
파일: meeting-2026-02-02.md
언어: ko-KR
길이: 00:45:32
화자: 4
단어 수: 6,842
처리 시간: 127초
📝 생성됨:
- meeting-2026-02-02.md (Markdown 보고서)
🎯 다음 단계:
1. 회의록 및 실행 항목 검토
2. 참가자와 보고서 공유
3. 실행 항목 추적 및 완료
예시 3: 일괄 처리
사용자 입력:
copilot> 이 오디오 파일들을 변환: recordings/*.mp3
스킬 출력:
📦 일괄 모드: 5개 파일 발견됨
1. team-standup.mp3
2. client-call.mp3
3. brainstorm-session.mp3
4. product-demo.mp3
5. retrospective.mp3
🎙️ 일괄 처리 중...
[1/5] team-standup.mp3 ✅ (2분 34초)
[2/5] client-call.mp3 ✅ (15분 12초)
[3/5] brainstorm-session.mp3 ✅ (8분 47초)
[4/5] product-demo.mp3 ✅ (22분 03초)
[5/5] retrospective.mp3 ✅ (11분 28초)
✅ 일괄 완료!
📝 5개의 Markdown 보고서 생성됨
⏱️ 총 처리 시간: 6분 15초
예시 5: 큰 파일 경고
사용자 입력:
copilot> 오디오를 Markdown으로 변환: conference-keynote.mp3
스킬 출력:
✅ Faster-Whisper 감지됨 (최적화됨)
📂 파일: conference-keynote.mp3
📊 크기: 87.2 MB
⏱️ 길이: 02:15:47
⚠️ 큰 파일 (87.2 MB) - 처리에 몇 분 정도 걸릴 수 있음
계속하시겠습니까? [Y/n]:
사용자: Y
🎙️ 처리 중... (10-15분 정도 소요될 수 있음)
[████░░░░░░░░░░░░░░░░] 20% - 예상 남은 시간: 12분