AI 튜토리얼

Earshot으로 코딩 에이전트에 오디오 분석 및 사운드 합성 기능 제공하기

Earshot 설치 방법, 명령줄 또는 Python으로 오디오 검사하기, 녹음에서 이벤트 찾기, 영화 사운드트랙 평가하기, 지속형 MCP 서버 실행하기, Forge로 코드 합성 효과음 생성하기를 알아보세요.

2026년 10월 16일약 16분 소요

Earshot으로 코딩 에이전트에 오디오 분석 및 사운드 합성 기능 제공하기

Earshot의 기능

Earshot은 AI 코딩 에이전트를 위해 설계된 로컬 오디오 분석 및 사운드 합성 도구 키트입니다. 사운드를 구조화된 근거로 변환합니다. 여기에는 자연어 설명, 보정된 매칭 점수, 시간 지정 이벤트, 객관적 측정값, 시각적 사운드 시트, 출시 영상 비평이 포함됩니다.

예를 들어 특정 효과음이 깊고 기계적인 키 입력 소리처럼 들리는지, 긴 녹음에서 특정 이벤트가 어디에서 발생하는지, 두 후보 사운드가 어떻게 다른지, 사운드트랙이 영상 컷에 맞는지 등을 확인할 수 있습니다. earshot forge를 사용하면 코드로 효과음을 합성할 수도 있습니다.

Earshot은 CPU에서 로컬로 실행되며, 명령줄 인터페이스, Python API, Claude Code와 같은 도구를 위한 MCP 서버를 제공합니다. 초기 모델 다운로드가 완료되면 표준 분석 기능을 오프라인에서도 사용할 수 있습니다.

주요 기능

사운드 설명: describe는 보정된 태그, 대안 해석, AudioSet 레이블, 측정값을 반환합니다.
후보 매칭 및 순위 지정: match는 파일 하나가 설명에 얼마나 잘 맞는지 평가하고, rank는 쿼리를 기준으로 여러 파일의 순위를 지정합니다.
이벤트 찾기: find는 긴 녹음에서 가장 잘 일치하는 순간을 식별하고 트리밍에 바로 사용할 수 있는 시작 및 종료 시간을 보고합니다.
오디오 비교: compare는 참조 녹음을 검색하고, ab는 두 사운드 또는 트림 사이의 차이를 설명합니다.
실재감 평가: realness는 오디오가 코드로 합성된 사운드보다 실제 녹음 또는 전문적으로 제작된 녹음에 가까운지 추정합니다.
사운드트랙 분석: timeline은 이벤트, 섹션, 레벨, 비트, 그리고 비디오 컷 또는 큐 프레임과의 동기화를 식별합니다.
시각적 보고서 생성: sheet는 비디오 프레임, 이벤트, 섹션, 파형, 스펙트로그램, 음량, 동기화 마커가 포함된 주석 처리된 PNG를 생성합니다.
출시 영상 비평: critique는 전문 출시 영상 7편으로 구축한 프로필과 영상을 비교하고 타임스탬프가 포함된 수정 사항을 제안합니다.
객관적 측정: measure는 모델을 사용하지 않고 LUFS, 트루 피크, 음량 범위, 엔벌로프, 스펙트럼, 템포, 키 등의 속성을 보고합니다.
효과음 합성: forge는 코드로 사운드를 렌더링하고 Earshot의 평가 도구와 모델을 사용하지 않는 측정값으로 레시피 매개변수를 검색합니다.

Earshot 설치

사전 요구 사항

Python 3.10 이상이 필요하며, 시스템 경로에서 ffmpeg와 ffprobe를 모두 사용할 수 있어야 합니다. Earshot은 CPU 전용이며 GPU를 사용하지 않습니다.

환경 생성

git clone https://github.com/Leonxlnx/earshot
cd earshot
python -m venv .venv
.venv/bin/python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
.venv/bin/python -m pip install -e ".[mcp,llm,dev]"
.venv/bin/python -m earshot doctor --load

Windows에서는 .venv/bin/python을 .venv/Scripts/python으로 바꾸세요.

모델을 사용하는 첫 작업에서는 저장소 내부의 .cache/hf에 약 1.4 GB를 다운로드합니다. 단, EARSHOT_HOME을 설정하면 캐시 위치를 변경할 수 있습니다. Earshot은 텍스트-오디오 임베딩에 CLAP 모델 laion/larger_clap_general을 사용하고, AudioSet 태깅에 MIT/ast-finetuned-audioset-10-10-0.4593을 사용합니다.

종속성, 데이터 파일, 모델, 정밀도 또는 CPU 설정을 확인해야 할 때마다 진단 명령을 실행하세요.

.venv/bin/python -m earshot doctor --load

CPU 및 캐시 설정 구성

EARSHOT_THREADS는 Torch CPU 스레드 수를 제어합니다.
EARSHOT_HOME은 캐시 루트를 변경합니다.
EARSHOT_PRECISION=fp32는 FP32를 강제합니다. 기본값은 네이티브 지원 CPU에서만 BF16이며, 그 외에는 FP32입니다.
EARSHOT_OFFLINE=1은 모델을 다운로드한 후 오프라인 작업을 활성화합니다.

기본 명령줄 사용법

사운드 설명

익숙하지 않은 파일을 간결하게 설명하려면 describe로 시작하세요.

earshot describe enter.ogg

요약에는 재생 시간, 트랜지언트 형태, 가능성이 높은 사운드 범주, 보정된 z 점수, 피크 레벨, 밝기, 대안 해석이 포함될 수 있습니다. 전체 구조화된 결과를 확인하려면 --json을 추가하고, 저장하려면 --out result.json을 추가하세요.

특정 설명 테스트

원하는 사운드를 이미 알고 있다면 match를 사용하세요. 대안 설명을 지정하면 대상과 혼동하기 쉬운 사운드를 구분하는 데 도움이 됩니다.

earshot match key.ogg "a deep thocky mechanical keyboard press" --alts "a clicky blue switch keyboard" "a mouse click"

결과에는 코사인 유사도, 어휘 보정 z 점수, 그리고 강함, 그럴듯함, 약함, 일치하지 않음과 같은 판정이 포함됩니다.

여러 후보 파일 순위 지정

컬렉션에서 가장 적합한 후보를 선택하려면 설명 뒤에 파일 경로를 전달하세요.

earshot rank "a fast crisp air whoosh" sounds/one.wav sounds/two.wav sounds/three.wav

에이전트가 가능한 효과음을 여러 개 다운로드하거나 렌더링한 뒤 근거에 기반해 순서를 정해야 할 때 유용합니다.

긴 녹음에서 이벤트 찾기

find 명령은 녹음 안에서 검색하고 샘플 트리밍 시간을 반환합니다.

earshot find keys.ogg "a single mechanical key press" --top 4

각 결과에는 시작 시간, 종료 시간, 지속 시간, 점수 및 판정이 포함됩니다. 그런 다음 이러한 타임스탬프를 사용해 더 큰 소스에서 정리된 이벤트를 추출할 수 있습니다.

모델 해석 없이 측정하기

의미론적 판단이 아니라 재현 가능한 오디오 속성이 필요할 때는 measure를 사용하세요.

earshot measure soundtrack.wav --json

이 명령은 음량, 트루 피크, 음량 범위, 엔벌로프, 스펙트럼, 템포 및 키를 비롯한 객관적인 정보를 보고합니다.

영화 사운드트랙 분석

청취 타임라인 만들기

timeline을 사용하면 초 단위 청취 트랜스크립트를 만들 수 있습니다. 비디오를 제공하면 Earshot가 화면 전환 및 큐 프레임과의 동기화를 평가합니다.

earshot timeline soundtrack.wav --video film.mp4 --json

결과에는 감지된 이벤트, 섹션, 레벨, 음량, 비트 그리드 및 시청각 동기화 근거가 포함될 수 있습니다.

주석이 포함된 사운드 시트 만들기

사운드 시트는 주요 분석 레이어를 하나의 이미지에 배치하여 시각 에이전트가 검사할 수 있도록 합니다.

earshot sheet soundtrack.wav --video film.mp4 -o out.png

프레임, 오디오 이벤트, 파형, 스펙트로그램 및 동기화를 보여 주는 Earshot 시트

생성된 PNG에는 대표 프레임, 라벨이 지정된 이벤트, 섹션, 파형, 스펙트로그램, 음량, 비트 및 동기화 마커를 함께 포함할 수 있습니다.

런치 필름 비평 생성하기

critique를 실행하면 영화와 Earshot에 포함된 7편의 전문 런치 필름 프로필을 비교할 수 있습니다.

earshot critique film.mp4

보고서에는 판정이 제시되고, 프로필 범위 안팎에 있는 지표가 식별되며, 타임스탬프가 포함된 수정 사항의 우선순위가 지정됩니다. 이를 보편적인 품질 척도가 아니라 특정 런치 필름 스타일과의 비교로 받아들이세요.

감탄하는 영화들로 직접 프로필을 만들 수도 있습니다.

earshot profile reference-one.mp4 reference-two.mp4 reference-three.mp4 -o custom-profile.json

Python에서 Earshot 사용하기

Python 인터페이스를 사용하면 각 작업마다 새 프로세스를 실행하지 않아도 됩니다. 개별 CLI 호출은 모델을 로드하므로 반환되기까지 약 20~40초가 걸릴 수 있다는 점에서 유용합니다.

import earshot

earshot.describe("whoosh.wav")
earshot.find("typing.ogg", "a single isolated key press")
earshot.timeline("soundtrack.wav", video="film.mp4")

from earshot import api
api.rank("a crisp UI click", ["click-a.wav", "click-b.wav"])
api.critique("film.mp4")

earshot.api 네임스페이스는 순위 지정, 비평 및 다중 파일 실제성 분석을 비롯한 작업을 제공합니다. 이러한 호출을 하나의 Python 프로세스에서 유지하면 로드된 모델을 재사용할 수 있습니다.

Earshot를 MCP 서버로 실행하기

반복적으로 요청을 처리할 에이전트에는 별도의 CLI 호출보다 MCP 서버가 적합합니다. 첫 요청 이후에도 모델이 메모리에 유지되기 때문입니다.

claude mcp add earshot --scope user -e EARSHOT_THREADS=3 -- /path/to/earshot/.venv/bin/python -m earshot mcp

다른 MCP 호환 클라이언트의 경우 해당 클라이언트의 .mcp.json에 동등한 설정을 추가하세요.

{"mcpServers":{"earshot":{"command":"/path/to/earshot/.venv/bin/python","args":["-m","earshot","mcp"],"env":{"EARSHOT_THREADS":"3"}}}}

컴퓨터가 느린 경우 MCP_TIMEOUT=60000으로 Claude Code를 시작하세요. 선택 사항인 llm_critique 도구는 환경 변수에서 GEMINI_API_KEY를 읽습니다. 설정 파일에 API 키를 직접 입력하지 마세요.

Earshot Forge로 사운드 생성하기

Forge는 녹음된 오디오를 임베드하지 않고 사운드를 생성합니다. 레시피는 모달 공진기, 접촉 가진, 필터링된 노이즈, 계산된 룸 및 마이크 모델과 같은 물리적 합성 구성 요소를 사용합니다.

먼저 포함된 레시피를 나열하세요.

earshot forge

저장소에는 클릭, 충격음, 키 누름, 팝 및 휙 소리를 위한 레시피가 포함되어 있습니다. 실제 녹음을 참조로 사용해 키 누름 사운드를 검색하려면 다음을 실행하세요.

earshot forge keypress --refs path/to/real/keypresses/ --budget 144 --reps 2 --tone 1.5 --keep 4 --robust 8 --dir made/keypress

가능성 있는 혼동 대상을 지정하면서 특정 설명을 목표로 하려면 다음과 같이 실행하세요.

earshot forge whoosh --target "a fast crisp air whoosh" --alts "a wind gust" "a sword swing" --refs path/to/real/whooshes/ --tone 1.5 --dir made/whoosh

Forge는 매개변수화된 후보를 렌더링하고, 비평가로 점수를 매기며, 우수한 결과를 유지하고, 진화 탐색을 통해 후보를 변형합니다. 점수에는 설명 일치도, 지정된 대안, 추정 실제성, 참조와의 근접성, 측정된 형태, 음색 균형, 테일 동작 및 길이가 반영됩니다.

출력에는 다양한 WAV 파일과 후보 매개변수 및 점수가 포함된 report.json이 들어 있습니다. --robust N을 사용하면 선택된 후보가 새로운 무작위 시드로 다시 렌더링되므로, 한 번만 성공하는 것이 아니라 레시피가 계속 안정적으로 작동하는지 확인할 수 있습니다.

Forge 결과를 신중하게 판단하기

Forge는 Earshot 자체 모델을 기준으로 최적화하므로 모델 점수가 높다고 해서 사운드가 지각적으로 더 우수하다는 보장은 없습니다.

생성된 사운드의 1/3옥타브 균형, 테일 및 길이를 참조 녹음과 비교하세요. 참조 음원과 나란히 스펙트로그램을 검사하고, 견고성 재렌더링을 테스트하며, 품질이 중요한 경우 사람을 대상으로 한 블라인드 테스트를 진행하세요. README는 모달 공진기, 룸 응답 및 노이즈 플로어를 결합하는 등의 기법으로 실제성 모델이 속을 수 있다고 구체적으로 경고합니다.

고급 워크플로 팁

작업량에 맞는 인터페이스를 사용하세요. 몇 가지 조사에는 CLI가 편리합니다. 반복적으로 분석할 때는 모델이 계속 로드된 상태로 유지되도록 하나의 Python 프로세스나 MCP 서버를 사용하세요.
넓게 시작한 다음 가설을 검증하세요. describe를 실행해 대상 설명을 작성한 뒤, 명시적인 대안을 지정하여 match를 사용하세요.
의미론적 근거와 객관적 근거를 분리하세요. 모델 기반 판단을 measure, 톤 밸런스 검사, 파형 확인, 스펙트로그램과 결합하세요.
구조화된 출력을 저장하세요. 다른 프로그램이나 에이전트가 일반 언어 요약이 아닌 모든 필드를 검사해야 한다면 --json 또는 --out을 사용하세요.
실제 레퍼런스 녹음을 사용하세요. 레퍼런스 디렉터리는 비교와 Forge 평가를 개선하지만, 해당 녹음의 출처와 라이선스에 대한 책임은 여전히 사용자에게 있습니다.
포함된 에이전트 스킬을 설치하세요. skills/earshot 및 skills/real-sound를 ~/.claude/skills/ 또는 프로젝트의 .claude/skills/에 복사하거나 심볼릭 링크하세요. 이 스킬은 명령 선택, 판정 해석, 사운드트랙 제작, 믹싱, QA, 라이선스 확인을 설명합니다.

한계 이해하기

Earshot는 음량, 타이밍, 영상 동기화, 노출된 단일 사운드의 매칭, 후보 순위 지정, 명백한 코드 합성 소스 식별에 가장 강합니다. 복잡한 믹스에서 추출한 태그와 음악 장르 및 분위기 판단은 참고 정보로 취급해야 합니다.

Earshot는 취향, 감정, 출처, 라이선스 또는 음성 내용을 판단할 수 없습니다. 모델은 14kHz를 초과하는 주파수를 평가하지 않습니다. 실제 사운드 여부에 대한 판정은 증거일 뿐 확정적인 증명이 아니며, 기본 제공되는 실행 프로필은 이를 만드는 데 사용된 7개 영화만을 나타냅니다.

프로덕션 워크플로에서 점수에 의존하기 전에 저장소의 검증 문서에서 측정 결과를 확인하고, 한계 문서도 참조하세요.

결론

Earshot는 코딩 에이전트가 로컬 CPU 도구를 사용해 사운드를 검사하고 제작할 수 있는 실용적인 방법을 제공합니다. 먼저 describe, match, find를 사용하고, 완성된 영화에는 timeline, sheet, critique로 확장하세요. 전적으로 코드로 만든 매개변수화된 효과가 필요할 때는 Forge를 사용하세요. 신뢰할 수 있는 결정을 내리려면 모델 판정을 측정값, 레퍼런스 비교, 시각적 검사, 사람의 청취와 함께 활용하세요.