real_book

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.1.0] - 2025-11-23

### Added

#### Core Features
- **1,193 Jazz Standards** - Complete Real Book data loaded from `.jazz` files
- **10 Public API Functions** - Clean, functional interface for data access:
  - `get/1` - Retrieve song by title
  - `all/0` - Get all songs
  - `count/0` - Total number of songs
  - `search/1` - Filter by author, genre, year, or title
  - `random/1` - Random song with optional filters
  - `progression/1` - Get simplified chord progression
  - `chords/1` - Flat list of unique chords
  - `authors/0` - List all composers
  - `genres/0` - List all genres

#### Data Structures
- `RealBook.Song` - Complete song metadata and sections
- `RealBook.Section` - Key, time signature, and measures
- `RealBook.Measure` - Container for chord changes
- `RealBook.ChordBeat` - Chord with duration in beats
- Full integration with [Harmony](https://hex.pm/packages/harmony) library for chord analysis

#### Architecture
- GenServer-based in-memory storage for O(1) lookups
- Fast startup: loads all 1,193 songs at application start
- Read-only design: no mutations, simple mental model

#### Documentation
- Comprehensive README with API examples
- Complete moduledocs with examples for all public modules
- ExDoc configuration for HTML/EPUB generation
- ROADMAP with phases 1-5 development plan
- SESSION_NOTES tracking implementation decisions
- Integration examples for Discord bots, AI playlists, guitar simulators

#### Testing
- 7 comprehensive tests covering all major functionality
- Zero deprecation warnings
- Clean compilation with no warnings

### Fixed
- String.slice deprecation warnings (updated to Elixir 1.19 syntax)
- Type specs for better Dialyzer compatibility
- Pattern matching in parse functions for compile-time safety

### Changed
- Renamed `Chord` module to `ChordBeat` for clarity (chord + duration)
- Improved type spec from `Map.t()` to `%{String.t() => Section.t()}`

### Removed
- Empty test file (`test/real_book_test.exs`)
- Crash dump file

## Development Phases

### Phase 1: MVP (Completed) ✅
- Core API implementation
- Data loading and parsing
- Basic search and filter
- Documentation

### Phase 2: Architecture Refinement (Planned)
- Extract parser to separate module
- Improve separation of concerns
- Additional test coverage

### Phase 3: Enhanced Search (Planned)
- Search by key, chord, decade
- Similarity analysis
- Advanced filtering

### Phase 4: Melody Support (Planned)
- Melody data structures
- MusicXML import
- PDF OCR/OMR integration

### Phase 5: Advanced Features (Planned)
- MIDI generation
- Scale recommendations
- Voice leading analysis
- Transposition tools

## Known Limitations

### Current Scope
- **Chord progressions only** - No melody data yet (see Phase 4)
- **Single format** - Only `.jazz` files supported (MusicXML planned for Phase 2)
- **Read-only** - No API for modifying or adding songs

### Architecture
- Parser logic mixed with data structures (refactor planned for Phase 2)
- No indexing beyond title (could add author/genre indexes in Phase 3)

### Data
- Song data from iRb Corpus 1.0
- Some metadata may be incomplete (empty genre/year fields)
- Real Book copyright considerations if publishing to Hex

## Integration

RealBook is designed to integrate with other Elixir music projects:

- **discord_uzu** - Discord bot for practice suggestions
- **ai_playlists** - ML-based music recommendations
- **guitar_neck_simulator** - Chord visualization
- Other projects in the `~/dev/music` ecosystem

## Credits

- Jazz standard data sourced from iRb Corpus 1.0
- Built with [Harmony](https://hex.pm/packages/harmony) for music theory
- Humdrum-inspired `.jazz` file format

---

[0.1.0]: https://github.com/rpmessner/real_book_ex/releases/tag/v0.1.0