SonuSV7719/earshot

earshot: 에이전트를 위한 귀

당신은 소리를 들을 수 없습니다. earshot 판독 결과를 바탕으로 하지 않고 오디오가 어떤지, 또는 특정 소리가 "어울린다"고 절대 말하지 마십시오. 보고할 때는 숫자를 인용하십시오("강한 일치, z +3.9; p_real 0.96; -14.2 LUFS"). earshot은 로컬 CPU에서 실행되며(오디오는 선택적 llm 명령을 제외하고 기계 외부로 나가지 않음) 모든 임베딩과 결과를 디스크에 캐싱합니다. 비용: 각 CLI 호출은 먼저 모델을 로드하는 새 프로세스입니다(캐시된 파일의 경우에도 사용 중인 노트북에서 ~20-40초 소요). MCP 서버 또는 단일 Python 스크립트 내에서는 모델이 한 번 로드되고 반복 호출은 몇 초 내에 완료됩니다. 여러 번 호출해야 하는 경우 MCP 또는 짧은 스크립트(from earshot import api; api.find(...); api.realness(...))를 사용하십시오.

설정 (한 번만)

pip install -e "/path/to/earshot[mcp,llm]"   # 또는 저장소 venv 사용: /path/to/earshot/.venv/bin/python -m earshot ...
earshot doctor                           # 패키지, ffmpeg, 모델(고정된 리비전, 캐시 상태) 확인; --load 옵션으로 로드 시간 측정

동일한 기능을 제공하는 두 가지 사용 방식:

• CLI: earshot <명령어> ... [--json] [--out 결과.json]. 텍스트 출력은 일반 요약으로 시작합니다. 시간은 텍스트에서 m:ss.ss 형식, JSON에서는 초 단위입니다.
• MCP (모델이 호출 간에 로드된 상태 유지): claude mcp add earshot --scope user -e EARSHOT_THREADS=3 -- /path/to/earshot/.venv/bin/python -m earshot mcp, 또는 모든 클라이언트의 .mcp.json에서: {"mcpServers": {"earshot": {"command": "/path/to/earshot/.venv/bin/python", "args": ["-m", "earshot", "mcp"], "env": {"EARSHOT_THREADS": "3", "GEMINI_API_KEY": "${GEMINI_API_KEY:-}"}}}} (키 라인은 선택적 llm 도구에만 필요; Claude Code는 사용자 환경에서 이를 채우며, 다른 클라이언트는 해당 키를 실행 환경에 설정해야 할 수 있습니다: 프로젝트 파일에 리터럴 키를 절대 작성하지 마십시오). 도구: measure, describe, match, rank, find, compare, ab, realness, timeline, sheet, critique, doctor, llm_critique; 사운드 뱅크(모델 없음): sfx_list, sfx_render, kit_render (루프 5). 절대 경로를 전달하십시오; full=true는 모든 JSON을 반환합니다. 서버는 몇 초 내에 응답하며, 콜드 또는 사용 중인 머신에서는 더 오래 걸립니다. Claude Code에 earshot 도구가 표시되지 않으면 MCP_TIMEOUT=60000으로 시작하십시오(PowerShell: $env:MCP_TIMEOUT=60000; claude). earshot mcp --warm은 시작 시 모델을 미리 로드합니다. 기계가 공유되는 경우 EARSHOT_THREADS=2-3 (또는 모든 명령어에 --threads 2)을 설정하십시오. 프로세스의 첫 번째 모델 호출은 CLAP + AST를 로드합니다(~20-60초). 동일한 프로세스의 후속 호출은 빠릅니다. ffmpeg가 읽을 수 있는 모든 파일이 작동하며, mp4의 오디오도 포함됩니다(오디오 트랙이 없는 비디오는 그렇게 알립니다). 오류는 stderr에 한 줄로 표시됩니다: earshot <명령어>: error: ..., 종료 코드 1.

루프 1: 자산 선택

1. earshot rank "a soft felt mallet hit on a wooden block" downloads/sfx/ --top 5 - 폴더에서 후보 목록을 작성합니다.
2. earshot find winner.ogg "a single clean mallet hit" --top 3 - 샘플 트림(시작/끝 시간(초))으로 최상의 순간을 찾습니다. 각 세그먼트는 유형이 있습니다: stroke (하나의 발현이 감쇠할 때까지) 및 event (함께 속하는 스트로크, 예: 키 누름 + 뗌)는 어택 5ms 전에 시작하여 감쇠 후에 끝납니다. window는 가장자리가 원샷 쿼리(일반 스트레치, 크로스페이드용, 배경용)를 위해 소리에 스냅된 구간입니다. head / tail = 트림의 피크 대비 처음 5ms / 마지막 10ms의 음량(-30dB 이하 = 깨끗함). 'head cut' 또는 'tail cut'으로 표시된 트림은 소리 내부에서 시작하거나 끝납니다: 있는 그대로 사용하지 마십시오. --kind event는 온셋 기반 트림만 반환하고(히트, 클릭, 발소리), --kind texture는 일반 윈도우만 반환합니다(배경음). 기본값은 쿼리를 읽습니다.
3. earshot describe winner.ogg --start 1.12 --end 1.48 - 실제로 어떤 소리인지 설명합니다. 상위 태그가 필요한 것과 일치하는지, 형태(어택/디케이)가 그림과 일치하는지 확인하십시오. AudioSet 레이블은 약 0.5초 미만의 원샷에 대해 약합니다: 'tagger unsure' 또는 유사한 클래스(Zipper for a swish, Finger snapping for a click)는 중립적입니다. 완전히 다른 클래스(Speech, Music, Engine, Vehicle)만이 위험 신호입니다.
4. earshot realness winner.ogg --start 1.12 --end 1.48 (또는 전체 폴더) - 사용할 트림을 판단합니다: 멀티테이크 파일의 p_real은 모든 테이크와 그 사이의 무음에 대한 평균입니다. 사용자가 실제 또는 전문적으로 제작된 소리를 원할 때 '코드 합성 가능성 있음' 트림을 사용하지 말고, '불확실' 트림의 증거를 읽은 후 사용하십시오(사용 이유를 기록). 합성된 소리가 요점인 경우(절차적 음악, UI 톤, earshot forge로 만든 소리) realness는 정보일 뿐 장벽이 아닙니다. 판정 임계값은 길이에 따라 다릅니다(각 요약에 이름이 지정됨): 최대 6초의 소리는 클립 임계값(낮음 0.17 / 높음 0.77)을 사용하고, 더 긴 파일은 4초 윈도우의 평균을 약하게 보정된 파일 임계값(낮음 0.40 / 높음 0.77)과 비교하므로 다른 길이의 파일 간에 원시 p_real이 아닌 판정을 비교하십시오. 실제 녹음 및 전문적으로 제작된 음악과 사운드 디자인은 일반적으로 실제로 읽히지만, realness는 소리의 출처가 아니라 소리의 특성을 듣습니다: 깨끗하게 전문적으로 합성된 톤(UI 사운드, 차임, 신디사이저 스탭)도 코드 합성으로 읽힙니다. realness를 사용할 수 없는 경우(모델 누락) 실제 대 합성 여부가 확인되지 않았다고 명확히 말하십시오; describe의 AudioSet 클래스(Sine wave, Beep, Synthesizer)는 더 약한 증거입니다. 정확한 디지털 0만으로는 아무것도 증명할 수 없습니다(프로젝트의 라이선스 실제 녹음 중 59%에는 일부 편집 또는 페이드 패딩이 있습니다).
5. 두 후보 간에 선택하려면: earshot ab a.ogg b.ogg --query "a crisp fast air whoosh", find에서 얻은 트림에 대해 --a-start/--a-end/--b-start/--b-end 사용(A와 B는 동일한 멀티테이크 파일일 수 있음). 선택 사항: earshot match winner.ogg "a deep thocky key press" --alts "a clicky blue switch" "a typewriter key"로 하나의 주장을 테스트하거나, earshot compare winner.ogg --refs approved/ [--start --end]로 팔레트에 맞는지 확인합니다.

루프 2: 믹스 또는 영화 검토

1. earshot timeline film.mp4 --cues cues.json (또는 soundtrack.wav --video film.mp4) - 청취 기록: 시간, 레벨 및 태그가 있는 이벤트, 섹션, 음량 곡선, 화면 컷, 컷/큐당 동기화. --detail low는 빠르고, high는 최대 96개의 이벤트를 태그합니다(가장 중요한 것부터; 요약은 태그된 수를 알려주므로 태그되지 않은 이벤트가 누락된 소리를 의미하지는 않습니다). 동기화 통계를 읽으십시오: offset_ms = 소리 빼기 그림(음수 = 빠름), 'chance' 분수는 무작위 편집 지점이 얻을 점수를 말합니다. 우연보다 나은 동기화만 의미가 있습니다. 히트 없이 나열된 컷에도 부드러운 윙 소리가 있을 수 있습니다: 시트에서 확인한 후 소리를 추가하십시오.
2. earshot sheet film.mp4 -o sheet.png --cues cues.json (--from 10 --to 25 확대, --detail low는 더 빠름) - 주석이 달린 PNG: 프레임, 섹션, 레이블이 지정된 이벤트, 스펙트로그램, 음량, 비트, 동기화별로 색상이 지정된 큐 마커(녹색 = 프레임 내, 호박색 = 100ms 내, 빨간색 = 소리 없음). 이미지 리더로 PNG를 여십시오: 간격, 누적, 마스킹 및 늦은 히트가 한눈에 명확합니다.
3. earshot critique film.mp4 (--fast는 AudioSet / realness 패스를 건너뜀) - 측정된 전문 출시 영화 범위에 대한 점수 카드: 각 메트릭 ok / low / high와 가중치 및 타임스탬프가 있는 조치, 그리고 평결(출시 등급 / 근접 / 작업 필요 / 출시 등급 아님). 먼저 중요한 행을 수정하고, 새 렌더링에서 1-3을 다시 실행하십시오. "시각적 이벤트에서의 온셋" 점유율은 +-100ms 이내의 새로운 어택만 계산합니다(참조의 정의). 수정 및 팁은 timeline과 동일한 매처로 소리가 전혀 없는 컷을 지정합니다. 파일이 프로필 자체의 참조 영화 중 하나인 경우 critique는 이를 명시하고 다른 항목에 대해 점수를 매깁니다.
4. 언제든지 정확한 미터기(LUFS, 실제 피크 dBTP, LRA, 노이즈 플로어, 어택/디케이, 밝기, 밴드): earshot measure mix.wav [--music] 또는 MCP measure 도구.

루프 3: A/B 변경 비교

• earshot ab before.wav after.wav --query "warm punchy kick" 또는 --refs pro_refs/ - 어느 것이 더 가까운지, 그리고 B가 A와 측정된 단어(더 크게, 더 밝게, 더 긴 디케이)로 어떻게 다른지. 긴 파일 내부의 사운드의 경우 트림을 전달하십시오(--a-start 1.217 --a-end 1.615 --b-start 7.881 --b-end 8.285): 멀티테이크 파일의 전체 파일 A/B는 모든 테이크와 그 사이의 무음을 비교합니다. 그런 다음 earshot timeline after.wav를 실행하고 이전 실행과 이벤트 라인 및 동기화 통계를 비교하십시오. 한 번에 하나씩 변경하십시오.

루프 4: 코드로 소리 만들기 (earshot forge)

사용자가 선택이 아닌 소리를 만들고자 할 때 사용하십시오: 듣는 AI가 합성 코드를 작성하고, 듣고, 개선할 수 있습니다. 모든 샘플은 계산되어야 합니다(내부에 녹음된 오디오 없음, 임펄스 응답조차도). 실제 녹음은 비평가가 비교하는 참조일 뿐입니다.

1. earshot/forge/recipes/<name>.py: SPACE (매개변수 범위), DEFAULTS, TARGET, ALTS (현실적인 혼동) 및 render(params, r) -> 48 kHz 배열을 작성하거나 선택하십시오. earshot.forge.dsp (모달 공진기, 접촉 여기, 노이즈 색상, 시변 SVF, 계산된 룸, 노이즈 플로어가 있는 마이크)로부터 구축됩니다. 참조에서 측정된 실제 사물의 물리학을 모델링하십시오: 무엇이 무엇을 치는지, 무엇이 울리는지, 얼마나 오래 울리는지, 어떤 공간에서.

2. 한 라운드 실행: earshot forge <레시피> --refs <실제 참조> --budget 144 --reps 2 --tone 1.5 --keep 4 --robust 8 --dir <라운드 디렉토리>, 또는 모델을 한 번 로드하는 라운드당 하나의 Python 스크립트에서: forge(recipe, critic=Critic(target, alts, refs, tone=1.5), reps=2, space={...}).

   • --tone은 모델이 없는 음색 균형과 테일을 목적 함수에 넣습니다.
   • --reps 2는 각 후보를 2개의 렌더링으로 순위를 매기고, 운 좋은 렌더링에 반대합니다.
   • 사용 중인 노트북 CPU에서 160회 렌더링당 약 3-5분이 소요되며, 30-60초 모델 워밍업이 포함됩니다.

3. 그것이 들은 것을 읽으십시오. 각 선택의 요약은 예를 들어 "다음과 같이 들림: 코르크 팝, 유리 땡", "참조 대비 디케이 +2.4" 또는 "참조 중앙값에서 음색 11.2dB: 500-630Hz에서 +16dB(모든 참조 위)"라고 말합니다. 그런 다음 네 가지 방법으로 선택을 확인하십시오:

   • 모델이 없는 tone 단어: 모든 참조 외부에 속하는 대역, 에너지 점유율, 테일, 길이(모델 점수가 높을 때 가장 신뢰할 수 있는 신호)
   • robust: 가장 운 좋은 최상의 렌더링이 아닌 새로운 시드에 대한 평균
   • alt_zs: 어떤 혼동이 가장 가까운지
   • 참조 옆의 스펙트로그램: ffmpeg -i x.wav -lavfi showspectrumpic=s=900x360:scale=log:legend=0 x.png

   report.json의 AudioSet 태그는 선택하거나 안내할 때 사용하지 않는 한 보류됩니다. 보기 전에 선택 규칙(예: robust 평균)을 고정하고, 이후에 태그를 보고하십시오.

4. 잘못된 부분(누락된 릴리스 틱, 금속성 링, 너무 긴 테일)에 대해 레시피의 구조를 변경하고, 범위만 변경하지 마십시오. 그런 다음 반복하십시오. 각 라운드의 변경 사항과 숫자를 LOG에 기록하십시오.

5. 정직하게 보고하십시오. 동일한 비평가(report.json ref_scores, leave-one-out)가 점수를 매긴 실제 참조 옆에.

Goodhart, 명확히 말하십시오:

• 검색은 earshot 자체 모델을 최적화합니다. 만들어진 소리는 정기적으로 실제 녹음보다 모델에서 더 높은 점수를 받으며, 이는 비평가가 만족했다는 뜻이지 소리가 더 낫다는 뜻이 아닙니다.
• p_real은 속이기 쉽습니다: 모달 공진기와 룸 및 마이크 노이즈 플로어는 "실제"로 읽힙니다.
• 전형성은 참조의 평균이 되는 것을 보상합니다.
• 모델 검사는 포화됩니다: 검색 후, 모든 모델 검사, 보류된 표현 및 독립적인 실제 세트를 포함하여, 만들어진 소리를 실제 소리 안에 넣습니다. 측정과 귀만이 여전히 그것들을 구별할 수 있습니다.
• 참조에 대한 측정된 근접성으로 판단하십시오: 음색 균형, 모든 참조 외부의 대역, 테일, 길이. 또한 robust 재렌더링 및 스펙트로그램을 사용하십시오.
• 만들어진 소리를 "실제만큼 좋다"고 부르기 전에 인간 블라인드 테스트(무작위 순서, 음량 일치, 숨겨진 키)를 요청하십시오.

첫 번째 테스트(demo/forge-test)에서 독립적인 심사자는 키 누름이 실제 음색 균형에서 8-13dB 떨어져 있고 팝 소리가 긴 쉿하는 테일과 함께 대역 제한이 없다는 것을 발견했지만, 모든 모델 검사는 이를 실제라고 불렀습니다. 모델이 없는 검사로 안내하여 다시 만들었고, 이제 실제 녹음의 측정된 확산 내에 있습니다. 윙 소리는 진정으로 빠른 것으로 다시 만들어졌습니다. 임팩트(어둡고, 스웰 리드)와 클릭(짧은 테일)은 다시 만들어지지 않았습니다. 아직 인간이 듣지 않았습니다.

루프 5: 영화 사운드 키트 만들기 (earshot sfx / earshot kit)

코드로 만든 영화(시네틱 영화, 모든 큐 시트)에 효과가 필요할 때 사용하십시오: 신디사이저 음성을 작성하는 대신 earshot의 출고된 뱅크에서 렌더링합니다. 모델이 로드되지 않습니다. 전체 키트는 약 1분 안에 렌더링되고 재렌더링은 몇 초 만에 완료됩니다.

1. 사전 설정에서 시작: earshot kit init --preset calm -o audio/kit.json (텍스트 주도 영화용 calm, 에너지 넘치는 제품 영화용 crisp, 디자인된 효과 전용 영화용 minimal, 음악에 맞춰 편집된 영화용 launch). 각 역할의 note는 해당 사운드가 선택된 이유를 설명합니다. calm / crisp / minimal은 riser, swell 및 suck를 끕니다: 공개는 한 요소에서 해결되며 잠금은 하나의 깨끗한 히트입니다. launch는 섹션 변경 시 하나의 riser 또는 리버스 스웰을 사용하고 음악 주도 영화용으로 만들어진 0.4 사운드를 사용합니다(아래).
2. 영화에 맞게 조정: earshot sfx list --kind hit (또는 --category)는 길이, 피크 시간 및 노브와 함께 후보를 표시합니다. 역할의 sound를 변경하고, edits를 설정하고(pitch를 영화의 루트 키로 설정하여 히트 또는 드롭에 맞춤, 고정된 움직임을 위한 dur / apex), takes (타이핑의 경우 12 이상, 그 외에는 2-4), level_db를 설정합니다. earshot sfx render ID -o x.wav [--pitch E5] [--dur 0.8 --apex 0.32]로 후보 하나를 청취하고 측정된 온셋/피크/엔드를 읽으십시오.
3. 렌더링: earshot kit render audio/kit.json --out audio/kit. 테이크 및 kit.lock.json(측정된 온셋, 피크, 엔드, 테이크당 음량)은 믹서가 큐 프레임에 배치하는 것입니다: 히트 및 터치의 경우 프레임의 온셋, 윙 소리의 정점에 피크, riser의 히트에 엔드(역할이 peak에 정렬될 때의 피크, launch의 riser 및 swell이 그러하듯: 해당 멤버는 절정 후에 떨어집니다; kit check는 엔드 정렬된 것을 기록합니다).
4. 확인: earshot kit check audio/kit.json --out audio/kit. 렌더링에서 사용할 수 없는 것(사운드가 감당할 수 없는 노브 또는 피치, 0dB 초과 레벨, 필름의 cue 범위를 벗어난 테이크)을 거부합니다.
5. 렌더링된 키트를 소리내어 검토하려면 earshot timeline(루프 2)을 실행하십시오: 이펙트 TD가 각 큐에 대한 프레임, 레벨 및 동기화 통계를 확인할 수 있습니다. 모든 히트가 화면 컷에 있는지, 레벨이 균일하고 마스킹되지 않는지, 텍스처가 배경 위에 쌓여 있는지 확인하십시오.

일반 주의사항

• 경로: 항상 절대 경로를 사용하십시오. 상대 경로는 예측할 수 없게 동작합니다.
• 파일 형식: ffmpeg가 읽을 수 있는 모든 형식(wav, mp3, flac, ogg, mp4 등). 비디오 파일의 오디오 트랙이 자동으로 추출됩니다.
• 성능: 첫 번째 호출은 모델을 로드합니다(MCP에 연결하거나 Python 스크립트를 가져올 때, CLI 호출마다). 그 후 동일 프로세스 내 호출은 캐시된 결과와 로드된 모델로 인해 빠릅니다. 많은 파일에 대해 find/rank하는 경우 MCP를 사용하거나 짧은 Python 스크립트를 작성하여 모델을 한 번 로드하십시오.
• Goodhart 및 p_real에 대한 경고: 모델 최적화는 측정된 충실도와 항상 일치하지 않는 점수를 생성합니다. 모델이 없는 검사(측정, 스펙트로그램, 인간 청취)를 사용하여 forge 결과의 품질을 확인하십시오.
• 인간 청취는 forge 및 sfx 모두에 대한 최종 심판입니다: 작업이 완료되었다고 말하기 전에 인간에게 확인하도록 요청하십시오.
• MCP 타임아웃: Claude Code에서 earshot 도구가 표시되지 않으면 MCP_TIMEOUT을 늘리십시오(예: 60000ms).