Skip to main content

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

1

Access EmbyTok

Open EmbyTok in your browser. If you don’t have it running yet, see the installation section below.
2

Select Server Type

On the login screen, select Emby / Jellyfin from the server type selector.
3

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.
4

Connect & Browse

Click Connect. Once authenticated, you’ll see your video feed!
  • Swipe up/down to navigate between videos
  • Tap to play/pause
  • Swipe left/right to seek through the video
  • Tap the grid icon to switch to grid view

Authentication Implementation

EmbyTok uses the Emby REST API for authentication:
services/EmbyClient.ts
async authenticate(username: string, password: string): Promise<ServerConfig> {
  const cleanUrl = this.getCleanUrl();
  const response = await fetch(`${cleanUrl}/Users/AuthenticateByName`, {
    method: 'POST',
    headers: this.getHeaders(),
    body: JSON.stringify({
      Username: username,
      Pw: password,
    }),
  });

  if (!response.ok) {
    throw new Error('Emby Authentication failed');
  }

  const data = await response.json();
  return {
    url: this.config.url,
    username: data.User.Name,
    userId: data.User.Id,
    token: data.AccessToken,
    serverType: 'emby'
  };
}

Option 2: Connect to Plex

1

Get Your X-Plex-Token

You’ll need your Plex authentication token. Find it by:
  1. Open a media item in Plex Web
  2. Click > Get Info > View XML
  3. Look for X-Plex-Token in the URL
Keep your X-Plex-Token secure! It provides full access to your Plex server.
2

Select Plex Server Type

On the login screen, click the Plex button.
3

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
4

Connect

Click Connect to access your Plex library.

Option 3: Browse Local Folders

Perfect for watching videos on your device without a server.
1

Select Local Mode

On the login screen, click the 本地 (Local) button.
2

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
Option B: One-Time Load
  • Click 仅本次加载文件夹 (Load folder for this session only)
  • Choose your video folder
  • This won’t be saved for future sessions
3

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.
4

Start Watching

EmbyTok will scan your folder (including subfolders) for video files and start playing!

Supported Video Formats

EmbyTok recognizes these video extensions:
components/Login.tsx
const LOCAL_VIDEO_EXTENSIONS = new Set([
  'mp4', 'mkv', 'avi', 'mov', 'webm', 'm4v',
  'flv', 'wmv', 'ts', 'm2ts', '3gp'
]);

const isVideoFile = (file: File) => {
  if (file.type.startsWith('video/')) {
    // Filter out TypeScript files accidentally matched as .ts videos
    if (file.name.toLowerCase().endsWith('.ts') && 
        file.size < TS_VIDEO_MIN_BYTES) {
      return false;
    }
    return true;
  }
  const ext = file.name.slice(file.name.lastIndexOf('.') + 1).toLowerCase();
  return LOCAL_VIDEO_EXTENSIONS.has(ext);
};

Option 4: LAN File Server (Docker/NAS)

Ideal for sharing videos across devices on your local network.

Quick Docker Setup

1

Prepare Your Media Directory

Create a folder for your videos:
mkdir -p ./media
# Add your video files to ./media
2

Start with Docker Compose

git clone <repository-url>
cd embytok
docker compose up -d --build
This will:
  • Build the EmbyTok image
  • Start the web server on port 5176
  • Mount your ./media folder
3

Access Admin Panel

Open http://<your-ip>:5176/admin in your browser.
  • Admin Password: admin
Change the admin password in production by modifying the server code!
4

Configure Video Service

In the admin panel:
  1. Browse to your video folder (will show /media inside the container)
  2. Enter a Service Name (e.g., “My Movies”)
  3. Click Save and Set as Current
5

Connect from Other Devices

On any device on your network:
  1. Open http://<server-ip>:5176
  2. Select 文件服务 (File Service)
  3. Enter server address: http://<server-ip>:5176
  4. Select your service name from the dropdown
  5. Click Connect

Docker Environment Variables

# Server Configuration
PORT=5176                                    # Server port
HOST=0.0.0.0                                 # Listen address
SERVE_WEB=true                               # Serve web interface

# Paths
WEB_ROOT=/app/dist                           # Web files location
LAN_CONFIG_FILE=/app/data/lan-media-config.json  # Service config
MEDIA_ROOT=/media                            # Media directory
BROWSE_ROOTS=/media                          # Browsable directories

Alternative: Docker Run Command

docker run -d --name embytok --restart unless-stopped \
  -p 5176:5176 \
  -e HOST=0.0.0.0 -e PORT=5176 -e SERVE_WEB=true \
  -e WEB_ROOT=/app/dist \
  -e LAN_CONFIG_FILE=/app/data/lan-media-config.json \
  -e MEDIA_ROOT=/media -e BROWSE_ROOTS=/media \
  -v ./lan-media-config.json:/app/data/lan-media-config.json \
  -v ./media:/media:ro \
  embytok:latest

Development Setup

Want to modify EmbyTok or run it from source?
1

Clone the Repository

git clone <repository-url>
cd embytok
2

Install Dependencies

npm install
Requires Node.js v14 or higher.
3

Start Development Server

Web Only:
npm run dev:web
Web + LAN File Server:
npm run dev
This starts:
  • Vite dev server on port 5173
  • LAN file server on port 5176 (if using full dev mode)
4

Build for Production

npm run build
Output will be in the dist/ directory.

Development Script

The dev-with-lan.mjs script starts both servers concurrently:
scripts/dev-with-lan.mjs
import { spawn } from 'child_process';

const viteProcess = spawn('npm', ['run', 'dev:web'], { 
  stdio: 'inherit', 
  shell: true 
});

const lanProcess = spawn('npm', ['run', 'lan:server'], { 
  stdio: 'inherit', 
  shell: true 
});

process.on('SIGINT', () => {
  viteProcess.kill();
  lanProcess.kill();
  process.exit();
});

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

If you see CORS errors in the browser console:
  1. Emby/Jellyfin: Enable CORS in your server settings
  2. Plex: Use a reverse proxy like Nginx to add CORS headers
  3. Docker: Ensure you’re accessing via IP, not localhost (unless on same machine)
Make sure you:
  1. Created a service in the admin panel (/admin)
  2. Set the service as current
  3. Selected the correct service name on the login screen
  4. Verify API returns data: http://<ip>:5176/api/folder/videos?feedType=latest&serviceId=<id>
Browser Compatibility:
  • EmbyTok requires a modern browser with HTML5 video support
  • Safari may have limited codec support
Server Issues:
  • 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
This means architecture mismatch:
# On Mac with ARM, build for AMD64 (most NAS devices)
docker buildx build --platform linux/amd64 -t embytok:amd64 --load .
docker save -o embytok_amd64.tar embytok:amd64
Transfer the .tar file to your NAS and load it:
docker load -i embytok_amd64.tar
Having issues? Check the GitHub repository for more troubleshooting tips and community support.

Build docs developers (and LLMs) love