Practical Guides¶
Learn how to accomplish specific tasks with kernpy. These guides provide step-by-step instructions, code examples, and common patterns.
Getting Started¶
New to kernpy? Start here:
- Getting Started — Installation and core concepts
- Quick Start (5 min) — Minimal examples to get you rolling
Core Workflows¶
Parse and Analyze¶
Load **kern files, inspect structure, and extract musical information.
- Guide: Parse and Analyze
- Learn: How to load files, navigate the document structure, filter tokens by category
- Use when: You need to extract information from scores (pitches, durations, time signatures, etc.)
- Examples: Count notes in a score, analyze rhythmic patterns, batch process multiple files
Transform Documents¶
Filter, transpose, and modify scores to create new versions.
- Guide: Transform Documents
- Learn: How to filter spines, select measures, transpose, change encodings
- Use when: You need to create variations (transpositions, arrangements, simplifications)
- Examples: Transpose to new keys, extract single instruments, remove decorations
Build Processing Pipelines¶
Automate workflows for batch processing and complex data operations.
- Guide: Build Pipelines
- Learn: Batch processing, document concatenation, parallel processing, dataset creation
- Use when: You need to process many files or combine files in sophisticated ways
- Examples: Convert entire directories, transpose files in multiple keys, create CSV inventories
Command-Line Utilities¶
Work with kernpy from the shell without writing Python code.
- Guide: CLI Utilities
- Learn: Command-line commands, batch conversion, integration with shell scripts
- Use when: You prefer shell commands or need to integrate with bash/zsh scripts
- Examples: Convert kern to ekern, process Polish dataset, recursive directory processing
Advanced Topics¶
Sophisticated patterns and deep-dive topics.
- Transposition — All interval notation, batch transposition, key modulation
- Document Structure — Tree navigation, token manipulation, analysis patterns
- Custom Export — Complex filtering, multi-version creation, study editions
Quick Reference¶
| Task | Guide | Key Functions |
|---|---|---|
| Load and inspect a file | Parse and Analyze | kp.load(), doc.get_spines() |
| Transpose a score | Transform Documents | doc.to_transposed() |
| Remove decoration marks | Transform Documents | kp.dump(..., exclude={...}) |
| Extract single spine | Transform Documents | kp.dump(..., spine_ids=[0]) |
| Batch process files | Build Pipelines | Path.glob(), multiprocessing.Pool |
| Count pitches | Parse and Analyze | Loop + TokenCategory.PITCH |
| Convert format | CLI Utilities | python -m kernpy --kern2ekern |
Code Examples¶
Ready-to-use snippets for common tasks:
- Code Examples — 40+ complete, copy-paste examples organized by task
Troubleshooting¶
- FAQ — Solutions for common problems and questions
Learning Paths by Goal¶
Want to analyze music data? → Parse and Analyze → Document Structure → Code Examples
Want to create score variations? → Transform Documents → Transposition → Custom Export
Want to automate workflows? → Build Pipelines → Code Examples → CLI Utilities
Want to learn the fundamentals? → Getting Started → Core Concepts, Token Categories, Encodings → [Your chosen guide above]