# Symusic Dependency Taste > Decision framework for selecting and evolving third-party dependencies in symusic across C++, Python packaging, bindings, testing, and docs. Use when this capability is needed. - Skill: `tomevault-io/symusic-dependency-taste` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/symusic-dependency-taste` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/symusic-dependency-taste/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/symusic-dependency-taste --- # Symusic Dependency Taste and Selection Framework Use this skill when adding, replacing, or auditing dependencies. ## High-Level Dependency Philosophy 1. **Prefer focused libraries with clear performance or ergonomics wins.** - Symusic favors small, purpose-built components (parser, serializer, binding layer) over heavy frameworks. 2. **Keep the dependency surface narrow and intentional.** - Every added dependency increases wheel complexity, ABI risk, cross-platform CI cost, and maintenance burden. 3. **Keep core competency in-repo; outsource commodity building blocks.** - MIDI-domain semantics and transformation logic should stay first-party. - Generic concerns (formatting, UTF-8 helpers, serialization primitives) can be external. 4. **Choose libraries that align with cross-platform wheels and modern toolchains.** - Compatibility with C++20, Python 3.9+ wheels, and reproducible CI builds is non-negotiable. ## Existing Stack Taste Analysis ## C++/Core Dependencies - **`minimidi`**: chosen for fast and lightweight MIDI parsing; tightly aligned with symusic's core mission. - **`prestosynth`**: dedicated synthesis backend for SoundFont rendering, consistent with a focused audio-rendering layer. - **`pyvec`**: optimized container bridge that complements shared-pointer semantics and Python interop patterns. - **`nanobind`**: modern, efficient C++/Python binding layer; matches performance-first and typed API goals. - **`fmt`**: pragmatic formatting utility that improves clarity and maintainability over manual string assembly. - **`zpp_bits`** (header-only include): lightweight serialization building block for pickle support. - **`utfcpp` + small utility headers (`unordered_dense`, macros)**: low-level helpers kept lean and local where practical. **Taste signal:** this is a deliberately modular high-performance stack with minimal overlap between libraries. ## Python Runtime Dependencies - **`numpy`**: foundational numerical ecosystem choice; necessary for array-oriented conversions and interoperability. - **`pySmartDL`**: targeted utility for managed downloads in soundfont workflows. - **`platformdirs`**: minimal, standard choice for per-platform cache/config path correctness. **Taste signal:** runtime Python dependencies are intentionally few, stable, and functionally justified. ## Test/Dev Dependencies - **`pytest`, `pytest-cov`, `pytest-xdist`**: standard, scalable Python testing stack. - **`mypy`, `ruff` configuration in `pyproject.toml`**: static and style guardrails with pragmatic exceptions. - **`pretty_midi` (optional test extra)**: used as ecosystem interop/reference check rather than core runtime requirement. **Taste signal:** strong quality automation, but optional extras remain clearly separated from runtime essentials. ## Dependency Decision Rubric (Use Before Adding Anything New) A candidate dependency should pass all gates: 1. **Problem clarity**: Is there a repeated, non-trivial problem not already solved in-repo? 2. **Scope fit**: Does the library solve exactly that problem without pulling broad framework baggage? 3. **Performance profile**: Any predictable hot-path cost, memory overhead, or startup regression? 4. **Build/distribution impact**: Does it complicate wheels, ABI compatibility, or CI matrix reliability? 5. **Maintenance health**: Active releases, clear license, issue responsiveness, and transparent governance? 6. **Fallback plan**: Can we pin, patch, or replace it safely if upstream breaks? If any gate fails, prefer a smaller alternative or an internal implementation. ## Preferred Choices by Category - **Bindings:** stay with nanobind unless there is a compelling ABI/performance blocker. - **Numerics interop:** keep NumPy as the canonical Python array surface. - **Paths/platform behavior:** prefer tiny standard helpers like `platformdirs` over custom OS branching. - **Formatting/logging in C++:** keep `fmt` style consistency. - **Serialization:** keep lightweight binary serialization approaches; avoid monolithic runtime frameworks. ## Red Flags (Usually Reject) - Dependencies that duplicate existing stack capabilities with no measurable win. - Libraries with unstable release cadence or unclear licensing. - New runtime dependencies that are only needed for niche workflows (move those to optional extras). - Python-only workarounds for problems best solved once in C++ core. - Heavy frameworks that increase import/build time for marginal convenience. ## How to Document a Dependency Change For every addition/removal, include a short dependency decision record: - **Context:** what limitation or pain point triggered the change? - **Decision:** chosen library/version and integration boundary. - **Alternatives considered:** at least one rejected option and why. - **Consequences:** performance, binary size, CI, maintenance, and user-facing impact. - **Rollback strategy:** how to safely revert or swap in future. ## Minimal PR Checklist for Dependency Changes - Runtime vs optional extra placement is correct. - Lock/build metadata updated consistently. - Cross-platform build path is validated. - Tests cover new integration boundary. - Docs mention user-visible installation/runtime implications. --- > Source: [Yikai-Liao/symusic](https://github.com/Yikai-Liao/symusic) — distributed by [TomeVault](https://tomevault.io).