Quickstart Guide
This guide will get you watching your media collection in EmbyTok within minutes, whether you’re connecting to an Emby server, running locally, or deploying with Docker.Choose Your Path
Emby/Jellyfin
Connect to your existing media server
Local Folder
Browse videos from your device
Docker/NAS
Self-host on your network
Option 1: Connect to Emby/Jellyfin
Access EmbyTok
Open EmbyTok in your browser. If you don’t have it running yet, see the installation section below.
Enter Server Details
Fill in your server information:
- Server Address: Your Emby/Jellyfin URL (e.g.,
http://192.168.1.100:8096) - Username: Your Emby/Jellyfin username
- Password: Your password (optional for some servers)
The app automatically normalizes URLs. You can enter
192.168.1.100:8096 and it will add http:// for you.Authentication Implementation
EmbyTok uses the Emby REST API for authentication:services/EmbyClient.ts
Option 2: Connect to Plex
Get Your X-Plex-Token
You’ll need your Plex authentication token. Find it by:
- Open a media item in Plex Web
- Click … > Get Info > View XML
- Look for
X-Plex-Tokenin the URL
Enter Connection Details
- Server Address: Your Plex server URL (e.g.,
http://192.168.1.10:32400) - Username: Optional (defaults to “User”)
- X-Plex-Token / Password: Paste your X-Plex-Token here
Option 3: Browse Local Folders
Perfect for watching videos on your device without a server.Choose Folder Selection Method
You have two options:Option A: Set as Startup Folder (Recommended)
- Click 选择并设为启动目录 (Select and set as startup directory)
- Choose your video folder
- EmbyTok will remember this folder and auto-load it next time
- Click 仅本次加载文件夹 (Load folder for this session only)
- Choose your video folder
- This won’t be saved for future sessions
Grant Permissions
Your browser will ask for permission to access the folder. Click Allow.
EmbyTok uses the File System Access API, which is supported in modern browsers like Chrome, Edge, and Opera. Safari users should use the one-time load option.
Supported Video Formats
EmbyTok recognizes these video extensions:components/Login.tsx
Option 4: LAN File Server (Docker/NAS)
Ideal for sharing videos across devices on your local network.Quick Docker Setup
Start with Docker Compose
- Build the EmbyTok image
- Start the web server on port 5176
- Mount your
./mediafolder
Configure Video Service
In the admin panel:
- Browse to your video folder (will show
/mediainside the container) - Enter a Service Name (e.g., “My Movies”)
- Click Save and Set as Current
Docker Environment Variables
Alternative: Docker Run Command
Development Setup
Want to modify EmbyTok or run it from source?Start Development Server
Web Only:Web + LAN File Server:This starts:
- Vite dev server on port 5173
- LAN file server on port 5176 (if using full dev mode)
Development Script
Thedev-with-lan.mjs script starts both servers concurrently:
scripts/dev-with-lan.mjs
Video Feed Navigation
Once connected, here’s how to navigate:Gestures & Controls
- Swipe Up: Next video
- Swipe Down: Previous video
- Tap Video: Play/Pause
- Swipe Left/Right: Seek backward/forward
- Grid Icon: Switch to grid view
- Heart Icon: Like/Unlike video (adds to favorites)
- Volume Icon: Mute/Unmute
- Fullscreen Icon: Enter/Exit fullscreen
Browse Modes
Switch between modes in the top navigation:- 收藏 (Favorites): Your liked videos
- 随机 (Random): Randomized discovery
- 最新 (Latest): Newest videos first
Orientation Filter
In the menu (hamburger icon):- Vertical: Show only portrait videos (aspect ratio ≥ 0.8)
- Horizontal: Show only landscape videos
- Both: Show all videos
Next Steps
Configure Libraries
Manage which libraries appear in EmbyTok
Deploy to NAS
Complete guide for NAS deployment (Synology, etc.)
Build Android App
Package EmbyTok as a native Android app
iOS Native App
Build the UIKit-based iOS app with AVFoundation
Troubleshooting
Connection Failed - CORS Error
Connection Failed - CORS Error
If you see CORS errors in the browser console:
- Emby/Jellyfin: Enable CORS in your server settings
- Plex: Use a reverse proxy like Nginx to add CORS headers
- Docker: Ensure you’re accessing via IP, not localhost (unless on same machine)
No Videos Showing (File Server)
No Videos Showing (File Server)
Make sure you:
- Created a service in the admin panel (
/admin) - Set the service as current
- Selected the correct service name on the login screen
- Verify API returns data:
http://<ip>:5176/api/folder/videos?feedType=latest&serviceId=<id>
Videos Won't Play
Videos Won't Play
Browser Compatibility:
- EmbyTok requires a modern browser with HTML5 video support
- Safari may have limited codec support
- Check that video URLs are accessible (open in new tab)
- Verify transcoding settings in Emby/Plex if direct play fails
- For file server mode, ensure videos are MP4 format
Docker: exec format error
Docker: exec format error
This means architecture mismatch:Transfer the
.tar file to your NAS and load it:Having issues? Check the GitHub repository for more troubleshooting tips and community support.