MediaVault 📚

Previously PlaylistD - Now a Universal Media List Manager

MediaVault is a universal media list manager that follows the Unix philosophy: do one thing well. Manage playlists of any media type from any source with a clean Python API, CLI, and optional web interface.

✨ Features

• 🎯 Universal - Works with any media: YouTube, Vimeo, local files, any URL
• 🔌 Extensible - Plugin architecture for new sources and features
• 🐍 Pythonic - Clean, fluent API for developers
• 💾 Simple Storage - JSON-based, no database required
• 🚀 Fast - Efficient search with facets and suggestions
• 🌐 Web Interface - Beautiful dashboard (optional)
• 🔒 Secure - Input validation, path sanitization, thread-safe

🚀 Quick Start

Install from PyPI

# Core package only
pip install mediavault

# With YouTube support
pip install mediavault[youtube]

# With API and Dashboard
pip install mediavault[api]

# Everything
pip install mediavault[all]

Basic Usage

# Create a playlist
mediavault playlist create "My Learning Path"

# List playlists
mediavault playlist list

# Import from YouTube (requires youtube plugin)
mediavault import "https://youtube.com/watch?v=..."

# Start interactive REPL
mediavault repl

# Start web interface
mediavault quickstart

🐍 Python API

from mediavault import PlaylistManager, PlaylistStorage, Video

# Initialize
storage = PlaylistStorage("./data")
playlists = PlaylistManager(storage)

# Create playlist with fluent API
playlist = (playlists.create("Python Tutorials")
    .with_description("Best Python learning resources")
    .tag("programming")
    .tag("python")
    .save())

# Add videos
video = Video(
    title="Python in 100 Seconds",
    url="https://youtube.com/watch?v=...",
    duration=100
)
playlist.add_video(video)

# Search
from mediavault import SearchEngine
search = SearchEngine(storage)
results = search.search("python", limit=10)

🔌 Plugin System

MediaVault uses a plugin architecture for extensibility:

from mediavault import Plugin

class MyPlugin(Plugin):
    name = "My Custom Plugin"
    version = "1.0.0"
    
    def get_importers(self):
        return {"mysource": self.import_from_mysource}

Available Plugins

• youtube - Import videos, playlists, channels from YouTube
• api - RESTful API server (FastAPI)
• dashboard - Web interface
• More coming soon: vimeo, twitch, local files

🏗️ Architecture

mediavault/
├── core/           # Core functionality
│   ├── models.py   # Data models
│   ├── storage.py  # JSON storage
│   ├── search.py   # Search engine
│   └── plugin.py   # Plugin system
├── cli/            # CLI interface
├── plugins/        # Built-in plugins
└── integrations/   # External integrations

🎯 Novel Features

• Video Annotations - Add timestamped notes to videos
• Collaborative Playlists - Multi-user playlist curation
• Learning Paths - Track progress through educational content
• Smart Search - Full-text search with facets and ranking
• Playlist Analytics - View patterns and engagement metrics
• Cross-platform Import - YouTube, Vimeo, and more via plugins

📦 Installation Options

Development

# Clone repository
git clone https://github.com/queelius/mediavault.git
cd mediavault

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black mediavault/

🚧 Repository Rename Instructions

This repository is in the process of being renamed from playlistd to mediavault. To update your local clone:

# After GitHub rename is complete, update your remote:
git remote set-url origin https://github.com/queelius/mediavault.git

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. See CONTRIBUTING.md for guidelines.

📚 Documentation

• Package Summary - Overview of the package structure
• Code Review & Improvements - Recent improvements and fixes
• API Documentation - Full API reference
• Plugin Development - Create custom plugins

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

MediaVault is inspired by the Unix philosophy and tools like:

• git for its plugin architecture
• jq for JSON manipulation
• youtube-dl for media downloading concepts

Made with ❤️ for media collectors everywhere

Transforming how we organize and share media collections