Cách cung cấp cho tác tử lập trình khả năng phân tích âm thanh và tổng hợp âm thanh với Earshot

Earshot làm gì

Earshot là bộ công cụ phân tích âm thanh và tổng hợp âm thanh cục bộ dành cho các tác nhân lập trình AI. Công cụ chuyển âm thanh thành bằng chứng có cấu trúc: mô tả bằng ngôn ngữ tự nhiên, điểm tương đồng đã hiệu chuẩn, sự kiện theo thời gian, phép đo khách quan, bảng âm thanh trực quan và đánh giá phim ra mắt.

Công cụ có thể trả lời các câu hỏi như một hiệu ứng có giống tiếng nhấn phím cơ học trầm hay không, một sự kiện cụ thể xuất hiện ở đâu trong bản ghi dài, hai âm thanh ứng viên khác nhau như thế nào, hoặc nhạc nền có khớp với các lần cắt hình hay không. Công cụ cũng có thể tổng hợp hiệu ứng từ mã thông qua earshot forge.

Earshot chạy cục bộ trên CPU và có thể được sử dụng thông qua giao diện dòng lệnh, API Python và máy chủ MCP cho các công cụ như Claude Code. Sau khi tải mô hình ban đầu, các tính năng phân tích tiêu chuẩn có thể hoạt động ngoại tuyến.

Khả năng chính

• Mô tả âm thanh: describe trả về các thẻ đã hiệu chuẩn, những cách diễn giải thay thế, nhãn AudioSet và các phép đo.
• Đối sánh và xếp hạng ứng viên: match đánh giá mức độ một tệp phù hợp với mô tả, còn rank sắp xếp nhiều tệp theo một truy vấn.
• Tìm sự kiện: find xác định những thời điểm khớp nhất trong bản ghi dài hơn và báo cáo thời gian bắt đầu, kết thúc sẵn sàng để cắt.
• So sánh âm thanh: compare tìm kiếm các bản ghi tham chiếu, còn ab giải thích sự khác biệt giữa hai âm thanh hoặc đoạn cắt.
• Đánh giá độ chân thực: realness ước tính liệu âm thanh có giống bản ghi thực hoặc được sản xuất chuyên nghiệp thay vì âm thanh tổng hợp bằng mã hay không.
• Phân tích nhạc nền: timeline xác định các sự kiện, phần, mức âm lượng, nhịp và sự đồng bộ với các lần cắt video hoặc khung hình đánh dấu.
• Tạo báo cáo trực quan: sheet tạo tệp PNG có chú thích, chứa các khung hình video, sự kiện, phần, dạng sóng, phổ tần, độ lớn âm thanh và các dấu mốc đồng bộ.
• Đánh giá phim ra mắt: critique so sánh một bộ phim với hồ sơ được xây dựng từ bảy phim ra mắt chuyên nghiệp và đề xuất các chỉnh sửa kèm mốc thời gian.
• Đo lường khách quan: measure báo cáo các thuộc tính như LUFS, đỉnh thực, dải độ lớn, đường bao, phổ tần, nhịp độ và giọng mà không sử dụng mô hình.
• Tổng hợp hiệu ứng: forge kết xuất âm thanh từ mã và tìm kiếm các tham số công thức bằng các bộ đánh giá của Earshot cùng các phép đo không dùng mô hình.

Cài đặt Earshot

Điều kiện tiên quyết

Bạn cần Python 3.10 trở lên, cùng với ffmpeg và ffprobe có thể truy cập thông qua đường dẫn hệ thống. Earshot chỉ sử dụng CPU và không dùng GPU.

Tạo môi trường

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

Trên Windows, thay .venv/bin/python bằng .venv/Scripts/python.

Thao tác đầu tiên sử dụng mô hình sẽ tải khoảng 1.4 GB vào .cache/hf bên trong kho lưu trữ, trừ khi bạn cấu hình EARSHOT_HOME. Earshot sử dụng mô hình CLAP laion/larger_clap_general cho các embedding văn bản-âm thanh và MIT/ast-finetuned-audioset-10-10-0.4593 để gắn nhãn AudioSet.

Chạy lệnh chẩn đoán bất cứ khi nào bạn cần xác minh các phần phụ thuộc, tệp dữ liệu, mô hình, độ chính xác hoặc cài đặt CPU:

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

Cấu hình CPU và bộ nhớ đệm

• EARSHOT_THREADS kiểm soát số luồng CPU của Torch.
• EARSHOT_HOME thay đổi thư mục gốc của bộ nhớ đệm.
• EARSHOT_PRECISION=fp32 buộc sử dụng FP32. Mặc định là BF16 trên CPU có hỗ trợ gốc và FP32 ở các nơi khác.
• EARSHOT_OFFLINE=1 bật chế độ ngoại tuyến sau khi các mô hình đã được tải xuống.

Sử dụng dòng lệnh cơ bản

Mô tả âm thanh

Hãy bắt đầu với describe khi bạn muốn có lời giải thích ngắn gọn về một tệp chưa quen thuộc:

earshot describe enter.ogg

Bản tóm tắt có thể bao gồm thời lượng, hình dạng âm đầu, các nhóm âm thanh có khả năng, z-score đã hiệu chuẩn, mức đỉnh, độ sáng và những cách diễn giải khác. Thêm --json để nhận kết quả có cấu trúc đầy đủ hoặc --out result.json để lưu kết quả.

Kiểm tra một mô tả cụ thể

Sử dụng match khi bạn đã biết âm thanh mình muốn tìm. Các mô tả thay thế giúp phân biệt mục tiêu với những âm thanh dễ bị nhầm lẫn:

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

Kết quả bao gồm độ tương đồng cosine, z-score được hiệu chuẩn theo từ vựng và kết luận như mạnh, có thể phù hợp, yếu hoặc không khớp.

Xếp hạng nhiều tệp ứng viên

Để chọn ứng viên tốt nhất từ một tập hợp, hãy truyền mô tả rồi đến các đường dẫn:

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

Điều này hữu ích khi một tác nhân đã tải xuống hoặc kết xuất một số hiệu ứng khả dĩ và cần sắp xếp chúng dựa trên bằng chứng.

Tìm một sự kiện trong bản ghi dài

Lệnh find tìm kiếm bên trong một bản ghi và trả về thời gian cắt theo mẫu:

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

Mỗi kết quả bao gồm thời gian bắt đầu, thời gian kết thúc, thời lượng, điểm số và phán định. Các mốc thời gian đó có thể được dùng để trích xuất một sự kiện rõ ràng từ nguồn lớn hơn.

Đo lường mà không cần mô hình diễn giải

Dùng measure khi bạn cần các thuộc tính âm thanh có thể tái lập thay vì các nhận định ngữ nghĩa:

earshot measure soundtrack.wav --json

Lệnh này báo cáo các thông tin khách quan, bao gồm độ lớn âm thanh, đỉnh thực, dải độ lớn, đường bao, phổ, nhịp độ và giọng.

Phân tích nhạc phim

Xây dựng dòng thời gian nghe

Dùng timeline để tạo bản chép lời nghe theo từng giây. Cung cấp video để Earshot đánh giá khả năng đồng bộ với các điểm cắt hình và khung hình đánh dấu:

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

Kết quả có thể bao gồm các sự kiện được phát hiện, các phần, mức âm thanh, độ lớn, lưới nhịp và bằng chứng đồng bộ âm thanh-hình ảnh.

Tạo bảng âm thanh có chú thích

Bảng âm thanh đặt các lớp phân tích chính vào một hình ảnh để tác nhân thị giác có thể kiểm tra:

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

PNG được tạo có thể kết hợp các khung hình đại diện, sự kiện được gắn nhãn, các phần, dạng sóng, phổ âm, độ lớn, nhịp và các dấu mốc đồng bộ.

Tạo bản phê bình phim ra mắt

Chạy critique để so sánh một bộ phim với hồ sơ đi kèm của Earshot về bảy phim ra mắt chuyên nghiệp:

earshot critique film.mp4

Báo cáo đưa ra phán định, xác định các chỉ số nằm trong hoặc ngoài phạm vi hồ sơ và ưu tiên các điều chỉnh kèm mốc thời gian. Hãy xem đây là phép so sánh với một phong cách phim ra mắt cụ thể, không phải thước đo chất lượng phổ quát.

Bạn cũng có thể xây dựng hồ sơ từ những bộ phim mình yêu thích:

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

Dùng Earshot từ Python

Giao diện Python tránh phải khởi chạy một tiến trình mới cho mỗi thao tác. Điều này hữu ích vì từng lệnh CLI sẽ tải các mô hình và có thể mất khoảng 20 đến 40 giây trước khi trả về.

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")

Không gian tên earshot.api cung cấp các thao tác như xếp hạng, phê bình và phân tích độ chân thực nhiều tệp. Giữ các lệnh gọi này trong cùng một tiến trình Python cho phép tái sử dụng các mô hình đã tải.

Chạy Earshot dưới dạng máy chủ MCP

Với tác nhân sẽ thực hiện các yêu cầu lặp lại, máy chủ MCP phù hợp hơn các lệnh CLI riêng lẻ vì các mô hình vẫn được giữ nóng sau yêu cầu đầu tiên.

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

Với một ứng dụng khách tương thích MCP khác, hãy thêm các thiết lập tương đương vào .mcp.json:

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

Trên máy chậm, hãy khởi động Claude Code với MCP_TIMEOUT=60000. Công cụ llm_critique tùy chọn đọc GEMINI_API_KEY từ môi trường. Không đặt khóa API dạng chữ trong tệp cấu hình.

Tạo âm thanh với Earshot Forge

Forge tạo âm thanh mà không nhúng âm thanh đã ghi. Các công thức của công cụ sử dụng những thành phần tổng hợp vật lý như bộ cộng hưởng modal, kích thích tiếp xúc, nhiễu đã lọc, phòng được tính toán và mô hình microphone.

Trước tiên, hãy liệt kê các công thức đi kèm:

earshot forge

Kho mã bao gồm các công thức cho tiếng click, va chạm, nhấn phím, tiếng nổ nhỏ và tiếng vút. Để tìm kiếm âm thanh nhấn phím bằng các bản ghi thực làm tham chiếu, hãy chạy:

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

Để nhắm đến một mô tả cụ thể đồng thời nêu tên các âm thanh dễ bị nhầm lẫn:

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 kết xuất các ứng viên có tham số, chấm điểm chúng bằng một bộ phê bình, giữ lại các kết quả tốt và biến đổi chúng qua quá trình tìm kiếm tiến hóa. Điểm số xét đến mức độ phù hợp với mô tả, các phương án thay thế được nêu tên, độ chân thực ước tính, độ gần với tham chiếu, hình dạng đo được, cân bằng âm sắc, đặc tính phần đuôi và thời lượng.

Đầu ra bao gồm các tệp WAV đa dạng và một report.json chứa tham số cùng điểm số của ứng viên. Với --robust N, các ứng viên được chọn sẽ được kết xuất lại bằng các seed ngẫu nhiên mới để bạn kiểm tra xem công thức có duy trì độ tin cậy hay chỉ thành công một lần.

Đánh giá cẩn thận kết quả của Forge

Forge tối ưu theo các mô hình của chính Earshot, vì vậy điểm số mô hình cao không đảm bảo âm thanh có chất lượng cảm nhận tốt hơn.

Hãy so sánh cân bằng một phần ba quãng tám, phần đuôi và thời lượng của âm thanh được tạo với các bản ghi tham chiếu. Kiểm tra phổ âm của nó bên cạnh các bản tham chiếu, thử kết xuất lại với độ bền và tiến hành kiểm thử mù với con người khi chất lượng quan trọng. README đặc biệt cảnh báo rằng mô hình độ chân thực có thể bị đánh lừa bởi các kỹ thuật như kết hợp bộ cộng hưởng modal, đáp ứng phòng và nền nhiễu.

Mẹo quy trình nâng cao

1. Sử dụng giao diện phù hợp với khối lượng công việc. CLI thuận tiện cho một vài lần kiểm tra. Hãy sử dụng một tiến trình Python hoặc máy chủ MCP để phân tích lặp lại, ताकि các mô hình được duy trì trong bộ nhớ.
2. Bắt đầu từ phạm vi rộng, sau đó kiểm tra các giả thuyết. Chạy describe, lập mô tả mục tiêu, rồi dùng match với các phương án thay thế cụ thể.
3. Tách biệt bằng chứng ngữ nghĩa và bằng chứng khách quan. Kết hợp các đánh giá dựa trên mô hình với measure, kiểm tra cân bằng âm sắc, phân tích dạng sóng và phổ đồ.
4. Lưu đầu ra có cấu trúc. Sử dụng --json hoặc --out khi chương trình hay tác nhân khác cần kiểm tra tất cả các trường thay vì chỉ phần tóm tắt bằng ngôn ngữ tự nhiên.
5. Sử dụng các bản ghi tham chiếu thực tế. Các thư mục tham chiếu giúp cải thiện việc so sánh và đánh giá Forge, nhưng bạn vẫn chịu trách nhiệm về nguồn gốc và giấy phép của những bản ghi đó.
6. Cài đặt các kỹ năng tác nhân đi kèm. Sao chép hoặc tạo liên kết tượng trưng cho skills/earshot và skills/real-sound vào ~/.claude/skills/ hoặc .claude/skills/ của dự án. Chúng trình bày cách chọn lệnh, diễn giải kết luận, sản xuất nhạc nền, phối âm, QA và kiểm tra giấy phép.

Hiểu các giới hạn

Earshot mạnh nhất trong việc phân tích độ lớn âm thanh, thời điểm, đồng bộ với hình ảnh, đối chiếu các âm thanh đơn lẻ dễ nhận biết, xếp hạng ứng viên và xác định các nguồn âm thanh được tổng hợp bằng mã một cách rõ ràng. Các nhãn được trích xuất từ bản phối phức tạp, cùng với phán đoán về thể loại và tâm trạng âm nhạc, chỉ nên được xem là gợi ý.

Công cụ này không thể xác định gu thẩm mỹ, cảm xúc, nguồn gốc, giấy phép hoặc nội dung lời nói. Các mô hình của nó không đánh giá những tần số trên 14 kHz. Kết luận về tính chân thực là bằng chứng chứ không phải sự chứng minh, và cấu hình khởi chạy tích hợp chỉ đại diện cho bảy bộ phim được sử dụng để tạo ra nó.

Hãy tham khảo tài liệu xác thực của kho mã để xem các kết quả đo được và tài liệu về giới hạn trước khi dựa vào điểm số trong quy trình sản xuất.

Kết luận

Earshot cung cấp cho các tác nhân lập trình một cách thực tế để kiểm tra và tạo âm thanh bằng các công cụ CPU cục bộ. Hãy bắt đầu với describe, match và find; chuyển sang timeline, sheet và critique khi làm việc với toàn bộ bộ phim; đồng thời sử dụng Forge khi cần tạo các hiệu ứng có tham số hoàn toàn bằng mã. Để đưa ra quyết định đáng tin cậy, hãy kết hợp kết luận của mô hình với các phép đo, so sánh tham chiếu, kiểm tra trực quan và việc nghe đánh giá của con người.