Skip to content

Frequently Asked Questions

Common questions about Media Viewer features, setup, and usage.

General

What is Media Viewer?

Media Viewer is a self-hosted web application for browsing and organizing your personal media collection. It provides a clean interface for viewing images and videos, with features like tagging, favorites, search, and progressive web app (PWA) support for mobile devices

Why did you make this? Why not use \<insert favorite app here>

The short version is because those apps didn't meet my needs, so I wrote this. This is not intended to replace those apps per se (I still use Immich, for example), but if you find it useful and compatible with what you want, great!

Did/do you use AI to help write this?

AI has been used throughout the development of this project as an assistant. Have a look at the AI disclosure document in the repo.

Is this a media manager app?

NO. The intention behind this app is one of viewing, meaning read-only access to the underlying library. The library features (tagging, favorites, etc.) are included to help search for what you want, but they are completely self-contained in the app.

Can I upload media through the app to my library?

NO. As above, this is intended as a viewer, not a manager. There is no intention of including this as a feature.

Is it vibe coded?

Like most things in the AI space, I think the term "vibe coded" is evolving. Initially, it meant any use of AI tools to generate code focusing on "vibes" rather than line-by-line coding and by that definition, the answer is yes.

However (and maybe I'm just saying this to make myself feel better), I think that true vibe coding is done by people who have no idea how to code and won't recognize problems in the code generated by AI. While I won't claim to be an expert developer, the amount of time I have spent diving deep into the code output by AI during the development of this application is likely far higher than your average "vibe coded in a weekend" project.

Is Media Viewer free?

Yes, Media Viewer is open source and free to use. It's licensed under the MIT License.

Can multiple users access Media Viewer?

Media Viewer is designed as a single-user application. While multiple people can use the same account, there's only one password and one set of favorites, tags, and preferences.

Why did you include WebAuthN/passkeys?

Being able to log in to the app on my mobile device with a fingerprint was a great quality of life improvement for the application. It should be noted that I don't really consider it a security feature (even though it does increase the security of the application if passkeys are used), largely because it's a single-user app that is not designed to be exposed to the web; it's purely for convenience when accessing the app.

What file formats are supported?

Media Viewer supports:

  • Images: JPEG, PNG, GIF, WebP, BMP, and other formats supported by browsers
  • Videos: MP4, WebM, MOV, AVI, MKV, and other formats (automatically transcoded if needed)
  • Playlists: Windows Media Player (.wpl) format

Why Windows Media Player playlists?

Because I have one particular playlist that I use often that is in that format.

Other playlist functionality is planned.

Do I need a powerful server to run Media Viewer?

No. Media Viewer is lightweight and runs efficiently on:

  • Raspberry Pi (ARM64)
  • Small VPS instances
  • NAS devices
  • Desktop computers

Memory usage scales with library size, but most collections run well with 512MB-1GB RAM.

Installation & Setup

How do I install Media Viewer?

The easiest method is using Docker Compose. See the Installation Guide for detailed instructions.

Can I run Media Viewer without Docker?

Yes, you can build and run Media Viewer directly from source. You'll need:

  • Go 1.21 or higher
  • FFmpeg installed
  • CGO enabled (for SQLite FTS5 support)

See Installation from Source for details.

How do I set up the initial password?

On first launch, Media Viewer will prompt you to create a password through the web interface. You can change it later in the Settings menu, or if you forget it, use the resetpw utility to reset it.

What directories need to be mounted?

Three directories are recommended:

  1. Media directory (/media): Your photos and videos (read-only)
  2. Cache directory (/cache): Thumbnails and transcoded videos
  3. Database directory (/database): SQLite database and metadata

Features

How does search work?

Media Viewer uses SQLite FTS5 (Full-Text Search) with trigram tokenization for fuzzy filename matching. You can also search by tags using tag:tagname syntax or exclude tags with -tag:tagname. See the Search Guide for details.

What are tags and how do I use them?

Tags are labels you can assign to files for organization. Examples: "vacation", "family", "2024". You can:

  • Add tags via the tag button on items
  • Bulk tag multiple items in selection mode
  • Search by tag using tag:tagname
  • Click any tag to search for items with that tag

See the Tagging Guide for more information.

What are favorites?

Favorites are items you pin to the top of your home page for quick access. They appear in a special section above the regular gallery.

Can I organize files into albums?

Media Viewer doesn't create albums, but you can:

  • Use your existing folder structure (folders appear as navigable directories)
  • Use tags to create virtual collections (e.g., tag items with "vacation 2024")
  • Add items to favorites for a quick access collection

Note that this functionality is planned.

Does Media Viewer support playlists?

Yes, Media Viewer supports Windows Media Player (.wpl) playlist files. It will display playlist files in the gallery, and clicking them opens a video player with the playlist contents.

Can you create playlists in the app?

No, Media Viewer does not currently have this functionality, but it is planned.

What is PWA mode?

Progressive Web App (PWA) mode allows you to "install" Media Viewer on mobile devices. It provides:

  • Home screen icon
  • Full-screen viewing
  • Faster load times

See PWA Support for details.

What are passkeys (WebAuthn)?

Passkeys are a modern authentication method using biometrics (fingerprint, face recognition) or hardware security keys. They're more secure and convenient than passwords. See WebAuthn/Passkeys Guide.

Thumbnails & Caching

How are thumbnails generated?

Thumbnails are generated:

  1. On-demand when you first view a file
  2. In background batches after indexing completes

They're stored in the cache directory for fast subsequent access.

Why are my thumbnails blurry or low quality?

Thumbnails are intentionally small (300x300px by default) for fast loading. To view full quality, click the item to open it in the lightbox viewer.

How do I regenerate thumbnails?

  1. Open Settings (gear icon)
  2. Go to the "Cache" tab
  3. Click "Regenerate Thumbnails"

This will delete all thumbnails and regenerate them on next access.

How much disk space do thumbnails use?

Thumbnail size varies by library, but expect roughly:

  • 20-50 KB per image thumbnail
  • 50-100 KB per video thumbnail

For a library of 10,000 files, thumbnails typically use 300-700 MB.

Video Playback

Why do some videos need to transcode?

Videos are transcoded if your browser doesn't natively support the codec. Media Viewer automatically detects this and transcodes to H.264/AAC (MP4), which is universally supported.

How long does transcoding take?

Transcoding is done in real-time as you watch. The video starts playing within seconds, and transcoding continues in the background. Transcoded files are cached for future viewing.

Can I disable transcoding?

Transcoding happens automatically only when needed. If your videos are already in browser-compatible formats (H.264/H.265), they'll stream directly without transcoding.

Where are transcoded videos stored?

Transcoded videos are stored in the cache directory under the transcode/ subdirectory. They're kept for future viewing to avoid re-transcoding.

Performance

Why is indexing slow on my NAS/NFS share?

Network filesystems add latency to each file operation. To improve performance:

  • Use async mount option for NFS
  • Increase INDEX_INTERVAL to reduce frequency
  • Monitor filesystem metrics to identify bottlenecks

See Troubleshooting for more details.

How can I monitor performance?

Media Viewer exposes Prometheus metrics on port 9090 internally (port 9091 when using Docker Compose). You can use Grafana or other monitoring tools to visualize:

  • Memory usage
  • Indexing performance
  • Filesystem latency
  • Search response times

See Metrics & Monitoring for details.

  • Organize files into subdirectories (avoid 10,000+ files in one folder)
  • Ensure thumbnails are generated
  • Check network connection if accessing remotely
  • Monitor server resources (CPU, memory, disk I/O)

Security & Privacy

Is Media Viewer secure?

Media Viewer includes several security features:

  • Password and/or passkey authentication
  • Session management with configurable timeouts
  • HTTPS support (when configured behind a reverse proxy)
  • Read-only media mounting option

See Security for best practices.

Should I expose Media Viewer to the internet?

Media Viewer is designed for personal/private use and it is not recommended to expose it to the internet. The app has some security features built into the backend to avoid common problems, but has not been tested to be secure when exposed.

However, if you must:

  • Use a reverse proxy with HTTPS, or something like CloudFlare tunnels
  • Set up strong authentication (passkeys recommended)
  • Consider VPN access instead of public exposure
  • Keep the software updated

How is my password stored?

Passwords are hashed using bcrypt before storage. The plaintext password is never stored in the database.

What data does Media Viewer collect?

Media Viewer is self-hosted and collects no data. All information stays on your server:

  • File metadata (paths, sizes, dates)
  • Tags and favorites you create
  • Thumbnails and transcoded videos
  • Authentication credentials (hashed)

Troubleshooting

I forgot my password. How do I reset it?

Use the resetpw utility:

docker exec -it <container-name> resetpw

See Troubleshooting for details.

Thumbnails aren't showing up. What's wrong?

Use the "Rebuild Thumbnails" button in the Settings (Gear Icon -> Cache tab -> Rebuild Thumbnails). Let the process run for a few minutes, then reload the page.

If that doesn't work, check:

  1. Cache directory is writable
  2. FFmpeg is available (for video thumbnails)
  3. Server logs for errors during thumbnail generation
  4. Disk space in cache directory

See Troubleshooting for more solutions.

Verify:

  1. Media directory is mounted correctly (docker exec -it <container> ls /media)
  2. Files have supported extensions
  3. Indexing has completed (check logs)
  4. File permissions allow reading

See Troubleshooting.

Media Viewer is using too much memory. How do I fix it?

During development, a library containing roughly 40,000 miscellaneous items is the target and memory usage was aggressively tuned. Thumbnail generation takes the most memory and because of how Go handles it, that size of library will typically cause the container to use between 1Gb and 1.5 Gb of memory, which will then drop to around 600-700 Mb for a steady state.

  1. Set GOMEMLIMIT environment variable to cap memory usage. Note that this might cause the container to get killed by Docker/Kubernetes.
  2. Reduce THUMBNAIL_INTERVAL frequency for very large libraries
  3. Reduce INDEX_INTERVAL frequency for very large libraries
  4. Monitor with Prometheus metrics
  5. Restart container periodically if needed

See Troubleshooting.

Advanced Topics

Can I customize the interface?

Currently, Media Viewer doesn't support themes or extensive customization. The interface is optimized for the default dark mode style.

Does Media Viewer support RAW image files?

Media Viewer displays whatever your browser can render. Most browsers don't natively support RAW formats (CR2, NEF, ARW, etc.). You would need to convert RAW files to JPEG/PNG first.

Can I use Media Viewer for music or audio files?

Media Viewer is designed specifically for images and videos. Audio files aren't currently supported.

How do I back up my Media Viewer data?

Back up these directories:

  1. Database directory: Contains SQLite database with tags, favorites, and metadata
  2. Cache directory (optional): Contains thumbnails and transcoded videos (can be regenerated)

Your original media files should have their own backup strategy.

Can I contribute to Media Viewer?

Yes! Media Viewer is open source. See the Contributing Guide for how to:

  • Report bugs
  • Suggest features
  • Submit pull requests
  • Improve documentation

Getting Help

Where can I get support?

How do I report a bug?

Open an issue on GitHub with:

  • Media Viewer version
  • Deployment method (Docker, source, etc.)
  • Steps to reproduce
  • Expected vs. actual behavior
  • Relevant log output

How do I request a feature?

Open a feature request on GitHub describing:

  • What you'd like to accomplish
  • Why it would be useful
  • Any relevant examples from other applications