Resonance/AGENTS.md

AGENTS.md

Build & Test

dotnet build              # Build all projects
dotnet test               # Run all tests
dotnet test --filter "FullyQualifiedName~ClassName.MethodName"  # Run single test

Architecture

• 3-project solution (src/Resonance.sln):
  • Core — class library: audio file scanning, metadata reading (ATL), SQLite persistence (Dapper)
  • Core.Tests — xUnit + FluentAssertions + Moq
  • AtlFieldExtractor — CLI that dumps ATL metadata fields from WAV files to .atl.txt
• No Avalonia UI yet — README mentions it but only the Core library exists.
• Target framework: net10.0 (requires .NET 10 SDK — currently 10.0.103).

Known Issues / Gotchas

• Table name mismatch: Database.InitializeDatabase() creates table sounds, but AddEntry() / AddEntries() / EntryExists() reference audio_files. Any call to insert or query will fail at runtime. Database currently has no test coverage.
• Tests create temp files/directories under Path.GetTempPath() and clean them up via IDisposable. Don't rely on a real audio directory for tests.
• AudioMetadataReader tests use real WAV files from data/source/ (not in git). When files are absent, tests silently return early (if (wavFiles.Length == 0) return;) — they pass without actually running assertions, not Skip.If. Running dotnet test will report 12 passes regardless of whether the fixture files exist.
• .atl.txt fixture files are generated by AtlFieldExtractor. If the WAV files or the ATL library version change, re-run the extractor to regenerate them before running metadata tests.

Data / Test Fixtures

• data/source/ 包含有版权保护的 WAV 音频文件，不会提交到 git。按厂商分子目录：Boom/、Wow Sound/、The Odessy/、Sound Idea/。
  • 每个 WAV 旁有对应的 .atl.txt 文件（由 AtlFieldExtractor 生成），记录了 ATL 库解析出的完整元数据，供测试断言参考。
  • Boom 目录下的文件元数据最丰富（标准标签 + iXML 自定义字段 + BWF bext 字段 + 嵌入封面）；Sound Idea 目录下的文件元数据最少（仅基础技术参数，无任何附加字段）。
• AudioMetadataReader 测试使用 data/source/Boom/ 和 Sound Idea/ 中的 WAV 文件。文件不在 git 仓库中，测试通过 if (wavFiles.Length == 0) return; 静默返回（测试仍然 pass，但未执行实际断言）。
• 路径解析：测试运行时从 bin/Debug/net10.0/ 启动，需向上回溯 6 级到达仓库根目录，再拼接 data/source/。

Conventions

• Code and comments are in Chinese.
• Namespace: OCES.Resonance.Core (Core), OCES.Resonance.AtlFieldExtractor (extractor), OCES.Resonance.Core.Tests (tests).
• Git commit style: WIP: <description> (no conventional commits).