Alexander
1374084135
docs/v1/ - Original beetfs documentation:
- analysis.md, components.md, data-flow.md, drawbacks.md
- features.md, modernization.md, rust-migration.md
- benchmark-plan.md, benchmark-results.md, e2e-test-plan.md
- README.md
docs/v2/ - New MusicFS architecture:
- requirements.md: Full requirements spec (FR-1 to FR-25, NFR-1 to NFR-14)
- P0: Multi-origin, plugins, CAS, control API
- P1: Search, album art, prefetch, metadata sources
- P3: HA, 10M+ files scalability
- architecture.md: Google BlueDoc style design document
- PlantUML diagrams for all components
- Design requirements with quantitative targets
- Alternatives considered, implementation plan
beetfs - Reverse Engineered Documentation
Status: Archived project (2010-2013), Python 2, fuse-python API Fork: git@github.com:LichHunter/beetfs.git Original: https://github.com/jbaiter/beetfs
Overview
beetfs is a FUSE filesystem that presents audio files with metadata from a database while passing through audio data unchanged from original files. This enables transparent metadata modification without touching the underlying files.
The Core Concept
┌─────────────────────────────────────────────────────────────────────┐
│ APPLICATION (VLC, Jellyfin, etc.) │
│ │
│ read("/mount/Artist/Album/track.flac") │
└─────────────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ beetfs (FUSE Layer) │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ FileHandler │ │
│ │ ┌──────────────────────────────────────────────────────────┐ │ │
│ │ │ if offset < header_boundary: │ │ │
│ │ │ return MODIFIED_HEADER (from beets database) │ │ │
│ │ │ else: │ │ │
│ │ │ return ORIGINAL_AUDIO (from real file on disk) │ │ │
│ │ └──────────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│ │
┌───────────┘ └───────────┐
▼ ▼
┌───────────────────┐ ┌───────────────────┐
│ Beets Database │ │ Original File │
│ (SQLite - tags) │ │ (untouched) │
│ │ │ │
│ title: "Fixed" │ │ [FLAC header] │
│ artist: "Corr" │ │ [Audio frames] │
│ album: "Right" │ │ │
└───────────────────┘ └───────────────────┘
Key Features
| Feature | Description |
|---|---|
| Metadata Overlay | Returns tags from database, not from file |
| Audio Passthrough | Original audio data served unchanged |
| Write Interception | Tag edits saved to database, not to file |
| Virtual Organization | Presents files in template-based directory structure |
| Format Support | FLAC (full), MP3 (partial - read-only) |
File Structure
beetfs/
├── beetsplug/
│ ├── __init__.py # Package initialization
│ └── beetFs.py # ALL code (~1144 lines)
├── README.rst # Original readme
└── COPYING # GPLv3 license
Quick Architecture Summary
| Component | Lines | Purpose |
|---|---|---|
beetFs (plugin) |
188-191 | Beets plugin hook |
mount() |
119-183 | CLI entry point, builds virtual tree |
FSNode |
390-436 | Virtual directory tree node |
FileHandler |
439-565 | CORE: Metadata interpolation |
InterpolatedFLAC |
274-388 | FLAC header generation |
InterpolatedID3 |
200-271 | ID3 tag generation (incomplete) |
beetFileSystem |
622-1144 | FUSE operations implementation |
Stat |
568-619 | File stat structure |
Documentation Index
- Architecture Overview - System design and component interaction
- Components Deep Dive - Detailed component analysis
- Data Flow - Read/write operation flows
- Performance Analysis - Latency, memory footprint, I/O patterns
- Drawbacks & Limitations - Known issues and missing features
- Modernization Guide - Notes for updating to Python 3
Critical Issues Summary
| Issue | Severity | Impact |
|---|---|---|
| Full file loaded into RAM | 🔴 Critical | OOM on large libraries |
| MP3 support disabled | 🔴 Critical | Only FLAC works |
| Python 2 only | 🔴 Critical | EOL, security risk |
| Single-threaded | 🟡 Major | Poor concurrency |
| 4 of 17 metadata fields | 🟡 Major | Limited functionality |
See drawbacks.md for complete list (27 identified issues).
Dependencies (Original)
beets >= 1.0
fuse-python (Python 2 FUSE bindings)
mutagen (audio metadata library)
Usage (Original)
# As beets plugin
beet mount /path/to/mountpoint
License
GPLv3 - See COPYING file