Frequently Asked Questions¶

Common questions about Peek Stash Browser.

General¶

What is Peek?¶

Peek is a modern web application for browsing and streaming Stash media content with real-time HLS transcoding. It provides a fast, responsive interface with adaptive quality streaming.

How is Peek different from Stash?¶

Peek is a browser/player focused on video playback, while Stash is a comprehensive media organizer. Peek:

• Focuses on smooth video playback with adaptive streaming
• Provides a simplified, browsing-focused interface
• Uses real-time transcoding for universal compatibility
• Complements Stash rather than replacing it

Does Peek modify my Stash library?¶

No. Peek is read-only. It connects to Stash's GraphQL API to read data but never modifies your library, files, or metadata.

Installation¶

What platforms are supported?¶

• unRAID: Community Applications or manual Docker install
• Docker: Any platform supporting Docker
• Development: Node.js 18+ on Windows/Mac/Linux

Do I need a separate database server?¶

No. Peek uses embedded SQLite. No PostgreSQL, MySQL, or other database server needed.

Can I run Peek and Stash on the same server?¶

Yes. They run as separate containers and don't conflict.

Video Playback¶

Why does transcoding take so long?¶

Transcoding is CPU-intensive. Performance depends on:

• Server CPU power
• Storage I/O speed (SSD vs HDD vs network)
• Original video codec and resolution
• Target quality selected

For best performance, use local SSD storage and allocate 2-4 CPU cores.

Can I play videos directly without transcoding?¶

Yes! Direct play is available when your browser supports the video codec. Use the quality selector and choose Direct to play the original file without transcoding.

When to use Direct: - Fastest playback (no transcoding delay) - Highest quality (original file) - Browser supports the video format

When to use transcoding: - Browser doesn't support the format - Want adaptive quality (switch between 720p/480p/360p) - Slower network connections

Can I download the original video file?¶

Not yet. Video downloads are planned for a future release. Currently, you can only stream videos through Peek's player.

Configuration¶

Where are my settings stored?¶

• User preferences: SQLite database in /app/data/peek-db.db
• Server config: Environment variables
• Temp files: /app/data/hls-cache/ (auto-cleaned)

How do I backup my data?¶

# Backup SQLite database
docker exec peek-stash-browser sqlite3 /app/data/peek-db.db ".backup /app/data/backup.db"

# Copy backup out of container
docker cp peek-stash-browser:/app/data/backup.db ./peek-backup.db

Can I customize the theme?¶

Yes! Peek includes several built-in themes and a custom theme editor.

Built-in Themes: - Light Mode - Dark Mode (default) - Deep Purple - The Hub

Custom Theme Editor: 1. Go to Settings → My Settings 2. Scroll to Custom Themes section 3. Create your own theme by choosing colors 4. Customize fonts, backgrounds, text colors, and more 5. Save and apply your custom theme

Toggle between themes using the theme icon in the navigation bar.

Performance¶

How many concurrent streams can Peek handle?¶

Depends on server CPU:

• 2 CPU cores: 1-2 streams at 720p
• 4 CPU cores: 3-4 streams at 720p
• 6+ CPU cores: 5+ streams at 720p

Lower qualities (480p, 360p) require less CPU and support more concurrent streams.

Why is my media loading slowly?¶

Check storage speed:

docker exec peek-stash-browser dd if=/app/media/test.mp4 of=/dev/null bs=1M count=100

If < 50 MB/s, media is likely on: - Network share (SMB/NFS) - Move to local storage - Slow HDD - Upgrade to SSD - USB drive - Use internal storage

How much disk space does Peek need?¶

• App data: ~100 MB (database, config)
• Temp files: ~50-100 MB per quality per minute of video
• Recommendation: 5-10 GB for temp storage on busy servers

Temp files are automatically cleaned up after 30 minutes.

Troubleshooting¶

Videos won't play¶

1. Check FFmpeg is installed: docker exec peek-stash-browser ffmpeg -version
2. Verify path mapping is correct
3. Check file permissions on media
4. Review backend logs for errors

See: Troubleshooting Guide

Can't connect to Stash¶

1. Verify STASH_URL is correct and accessible from container
2. Check Stash API key is valid
3. Test connectivity: docker exec peek-stash-browser curl http://stash:9999/graphql

Login doesn't work¶

• Check cookies are enabled
• Verify JWT_SECRET is set
• Try incognito mode
• Clear browser cache

Features¶

How do playlists work?¶

Playlists are fully available! Create custom playlists of your favorite scenes.

Creating a Playlist: 1. Click Playlists in the navigation 2. Click Create Playlist 3. Enter a name and description 4. Click Create

Adding Scenes: - Click the + icon on any scene card - Select the playlist to add it to - Or go to a scene's detail page and click Add to Playlist

Playing Playlists: - Click a playlist to view its scenes - Click Play to start from the beginning - Use Shuffle to randomize playback order - Use Repeat (all or one) for continuous playback - Reorder scenes by dragging them in edit mode

Does Peek track watch history?¶

Yes! Peek automatically tracks your viewing progress and lets you resume playback from where you left off.

Features: - Automatic progress tracking during playback - Resume from any device (synced to your user account) - "Continue Watching" section on home page - Progress bars on scene cards - Clear history for individual scenes or all at once

Can I use keyboard navigation?¶

Yes! Peek supports complete keyboard navigation, perfect for TV remotes or wireless keyboards.

Key features: - Arrow keys navigate scene grids and lists - Enter to select/play - Video player keyboard shortcuts (Space, arrows, F for fullscreen) - Playlist controls (N for next, P for previous) - TV Mode optimized for couch browsing

Can I use Peek on mobile?¶

Yes. The web interface is responsive and works on mobile browsers. A dedicated mobile app is not currently planned.

Does Peek support hardware transcoding?¶

Not yet. Hardware-accelerated transcoding (GPU) is planned for a future release to improve performance and reduce CPU usage.

Can I use Peek without Stash?¶

No. Peek requires a Stash server for media library management and metadata. Peek is designed as a companion to Stash, not a replacement.

Security¶

Is Peek secure?¶

Peek includes: - JWT authentication - Bcrypt password hashing - Read-only media access - Session management

Important: Change the default admin password immediately!

Should I expose Peek to the internet?¶

No. Peek is designed for local network use. For remote access: - Use VPN - Use reverse proxy with authentication layer - Don't expose directly to internet

Support¶

Where can I get help?¶

• Documentation: https://carrotwaxr.github.io/peek-stash-browser
• GitHub Issues: Bug reports and feature requests
• Stash Discord: #third-party-integrations channel

How do I report a bug?¶

1. Search existing issues first
2. Gather logs and error messages
3. Create detailed issue on GitHub
4. Include: version, platform, steps to reproduce

See: GitHub Issues

Can I contribute?¶

Yes! Contributions are welcome: - Code improvements - Bug fixes - Documentation - Translations (future)

See: GitHub Issues

Next Steps¶

• Installation - Install Peek
• Watch History - Resume playback from where you left off
• Keyboard Navigation - Complete keyboard shortcuts and TV mode
• Playlists - Create and manage custom playlists
• Troubleshooting - Fix common issues