Files

T

Alexander 1374084135 Reorganize docs into v1 (beetfs) and v2 (new architecture)

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

2026-05-12 16:46:37 +02:00

6.3 KiB

Raw Blame History

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

6.3 KiB Raw Blame History