Skip to content

MediaReel

MediaReel is a portable Windows desktop media launcher built around a local media.json catalog and bundled VLC playback.

It was originally designed for an event-use case: load the application, media catalog, posters, and VLC runtime onto a USB drive so the media collection could be carried between different rooms, plugged in, launched, and played with minimal setup. The goal was to make the media portable, predictable, and easy to start without needing a cloud service, a media server, a network share, or a complicated room-by-room setup.

Over time, the project grew from that USB/event workflow into a more general local media launcher: still portable, still local-first, but useful anywhere a self-contained media catalog and playback interface makes sense.

Summary

MediaReel reads a local JSON catalog, displays media entries as poster cards, and launches selected videos through bundled VLC. The application is intended to be portable, predictable, and easy to understand: place the app, catalog, media folder, poster folder, and VLC runtime together, then use the launcher as a local interface for playback.

At its core, MediaReel is a practical desktop utility for turning a folder-based media collection into something easier to browse and use.

Not everything needs a full server stack. Sometimes the answer is a clean local app that minds its business. Revolutionary, apparently.

Original event use case

The original idea came from needing a simple way to display and launch media during an event across multiple rooms.

The desired workflow was:

  • Prepare the media collection ahead of time
  • Store the app, catalog, media files, poster artwork, and VLC runtime together
  • Carry the full setup on a USB drive
  • Move the media collection between different rooms or machines
  • Launch the app without needing installation or cloud access
  • Start selected media quickly and reliably

That use case shaped the project’s priorities:

  • Portability mattered more than server-style complexity
  • Local playback needed to be dependable
  • The folder layout had to be understandable
  • The catalog needed to be editable without a database
  • The app needed to work without internet access
  • The release package needed to avoid accidentally including private or real media content

The USB origin is still visible in the design, but the project is no longer limited to USB-only use. It can run from any local folder layout that follows the expected packaged structure.

What it does

MediaReel provides:

  • A local desktop interface for browsing configured media entries
  • Poster-card display for movies or videos
  • Playback through bundled VLC
  • A JSON-based catalog format
  • Optional poster artwork
  • Optional descriptions and categories
  • Optional external subtitle support
  • A Config Builder/Editor for managing entries
  • Portable release packaging for Windows

The catalog is stored in media.json, which uses a top-level JSON array of media entries. Each entry requires a title and media file path, with optional fields for poster artwork, subtitles, description, and category.

Why I built it

Personal or event-based media collections can become awkward to use when everything is scattered across folders, filenames, posters, subtitles, and playback tools.

MediaReel is meant to make that experience more approachable without turning it into a giant platform. The goal is not to recreate Plex, Jellyfin, Netflix, or the entire entertainment-industrial complex in a trench coat.

The goal is simpler:

  • Keep media local
  • Keep configuration readable
  • Keep playback reliable
  • Keep the app portable
  • Keep the user experience clean

Key features

Local catalog

MediaReel uses a media.json file in the application root as its catalog. Entries can include:

  • title
  • file
  • poster
  • subtitles_enabled
  • subtitle_file
  • description
  • category

The config format is intentionally straightforward so the catalog can be edited directly or managed through the built-in editor.

Poster and metadata display

Entries can include poster paths and descriptions. If poster artwork is missing, blank, or unreadable, MediaReel falls back to a built-in placeholder image so the interface remains usable.

VLC playback

MediaReel launches media through bundled VLC using a local vlc/vlc.exe runtime. Playback does not require an internet connection or external account.

Subtitle support

MediaReel supports external subtitle files through subtitles_enabled and subtitle_file. Older configs using a legacy subtitle key are handled through backward-compatible migration behavior.

Config Builder/Editor

The app includes a configuration editor that supports creating, editing, duplicating, deleting, reordering, and saving catalog entries. This reduces the need to hand-edit JSON for routine changes.

Portable packaging

The packaged release layout is designed to be understandable:

MediaReel/
  MediaReel.exe
  media.json
  media/
    posters/
  vlc/
  docs/
    help.md
    config-format.md
    release-layout.md

The app uses a one-file PyInstaller build, while release packaging stages a clean, release-safe folder structure around the executable.

Technical design

MediaReel is intentionally local-first.

The application:

  • Reads local files
  • Loads local poster images
  • Opens local media through VLC
  • Does not require online services for normal operation
  • Treats media.json as trusted local input
  • Uses explicit process arguments when launching VLC rather than shell command interpolation

That trust model matters. The config is powerful enough to reference local paths, including paths outside the app folder if intentionally configured, but it is not treated as untrusted internet input.

Release and packaging work

A significant part of MediaReel is not just the app itself, but the packaging and release discipline around it.

The release process includes:

  • A defined packaged folder layout
  • A release-safe placeholder catalog
  • Sanitized staging before packaging
  • Bundled documentation files
  • VLC provisioning through a pinned artifact
  • SHA-256 verification for the pinned VLC ZIP
  • Release checklist documentation
  • Version alignment across application and package metadata

This makes the project more than “it runs on my machine.” The packaging work is focused on producing a repeatable release that does not accidentally ship local media, private catalog data, or a broken runtime layout.

Documentation and review

MediaReel includes supporting documentation for:

  • User help
  • Catalog/config format
  • Release layout
  • Security review
  • Repository audit
  • Documentation review

The documentation review identified and addressed release-readiness issues, including packaged help files not being staged correctly, missing user/developer README guidance, stale security-review language, and release layout mismatches.

The security review found no high-severity issues and confirmed several important design choices, including safe VLC process launching, local-only operation, defensive poster fallback behavior, and atomic config writes.

What it demonstrates

MediaReel is useful as a portfolio project because it shows more than just UI work.

It demonstrates:

  • Desktop application development
  • Local file and path handling
  • JSON configuration design
  • Backward-compatible config handling
  • User-facing editor workflows
  • External process launching
  • Release packaging
  • Runtime layout planning
  • Security and trust-model documentation
  • Documentation review and remediation
  • Practical release-readiness thinking

Current status

MediaReel is an active project with a working application concept, documented configuration format, packaging workflow, release layout, and review documentation.

Current focus areas include:

  • Improving user-facing documentation
  • Tightening release packaging
  • Improving developer setup
  • Expanding usability details
  • Continuing validation around packaged runtime behavior

Future improvements

Potential future improvements include:

  • Adding a requirements.txt or fuller dependency manifest
  • Documenting double-click-to-play behavior
  • Adding confirmation before reloading and discarding unsaved config editor changes
  • Continuing to improve packaged release testing
  • Adding screenshots or demo images to this portfolio page
  • Expanding the project page with architecture notes and release examples

Skills demonstrated

  • Python desktop application development
  • PySide6 UI design
  • JSON schema/config thinking
  • Local-first application design
  • Packaging and release engineering
  • Documentation discipline
  • Security review and remediation
  • User workflow design
  • Practical troubleshooting
  • Maintaining a clear trust model