iOS Native App Installation

EmbyTok includes a native iOS application built with UIKit and AVFoundation, providing native video playback with direct Emby and Folder Server integration.

Overview

The iOS app (EmbyTokNative) is located in the ios-native/ directory and includes:

Native iOS/iPadOS app with UIKit interface
AVPlayer-based video playback for smooth MP4 streaming
Native watchOS app (minimum watchOS 10.6) with disk cache
Direct MP4 stream support for Emby and Folder servers
Preloading and buffering for seamless playback

The iOS native app currently supports MP4 direct links. HLS and other formats can be added in future updates.

System Requirements

Development Mac

macOS with Xcode 15 or later

Target Devices

iOS 16+ / iPadOS 16+ devices

Apple ID

Free or paid Apple Developer account

watchOS (optional)

watchOS 10.6+ for Apple Watch app

Installation Steps

Open Xcode project

Navigate to the iOS project directory and open in Xcode:

cd ios-native
open EmbyTokNative.xcodeproj

Or from Finder, double-click EmbyTokNative.xcodeproj.

Configure code signing

In Xcode:

Select the EmbyTokNative project in the navigator
Select the EmbyTokNative target
Go to Signing & Capabilities tab
Select your Team from the dropdown
Xcode will automatically manage provisioning profiles

If you see “Bundle Identifier conflicts”, change the Bundle Identifier to a unique value (e.g., com.yourname.embytok).

Select target device

In the Xcode toolbar:

Click the device selector (next to the Run button)
Choose your connected iPhone/iPad
Or select a simulator for testing

For best performance testing, use a real device rather than simulator.

Build and run

Click the Run button (▶) or press Cmd+R.Xcode will:

Build the application
Install on your device
Launch EmbyTok automatically

Trust developer certificate (first time)

On your iOS device:

Go to Settings > General > VPN & Device Management
Find your developer certificate
Tap Trust to allow the app to run

Building watchOS App (Optional)

The project includes a native Apple Watch companion app:

Install watchOS components

If not already installed:

Open Xcode
Go to Xcode > Settings > Components
Download watchOS platform components

Select watch target

In Xcode:

Change scheme to EmbyTokWatch
Select your Apple Watch as target device

Build and run

Click Run to install on your Apple Watch.Features:

Server connection
Pure mode toggle
Mute control
Disk cache prefetch for smooth playback

Network Configuration

App Transport Security

The app allows HTTP connections for local servers via NSAppTransportSecurity settings. In Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

HTTP is allowed for development and local network access. For production apps connecting to remote servers, use HTTPS or add specific domain exceptions.

Connecting to Servers

EmbyTok iOS supports:

Emby servers (MP4 direct stream)
Folder Server (LAN file server mode)

Ensure your iOS device can reach the server on your local network.

Using the iOS App

Launch EmbyTok

Open the app on your iOS device.

Select connection type

Choose between:

Emby: Connect to Emby media server
Folder: Connect to EmbyTok folder server

Enter server details

For Emby:

Server URL: http://192.168.1.100:8096
Username and password

For Folder Server:

Server URL: http://192.168.1.100:5176
Service name or ID in password field

Start browsing

Swipe vertically to browse videos in TikTok-style interface.

Video Playback Features

The native iOS app includes:

AVPlayer Integration

Native AVFoundation video playback
Hardware-accelerated decoding
Smooth seeking and scrubbing
Picture-in-picture support (if enabled)

Preloading and Buffering

// Example configuration
AVPlayerItem.preferredForwardBufferDuration = 10.0

Preloads next 2 videos for seamless browsing
Configurable buffer duration
Efficient memory management

Cache Management (watchOS)

watchOS app includes disk cache:

Location: Caches/EmbyTokWatchCache
Prefetches current and next videos
Automatic cache cleanup

Xcode Project Structure

ios-native/
├── EmbyTokNative.xcodeproj/     # Xcode project
├── EmbyTokNative/               # iOS app source
│   ├── ContentView.swift        # Main UI
│   ├── VideoPlayer.swift        # AVPlayer wrapper
│   ├── Models/                  # Data models
│   └── Info.plist              # App configuration
├── EmbyTokWatch/                # watchOS app (optional)
└── README.md                    # iOS-specific docs

Development Workflow

Making Code Changes

Edit Swift files

Modify source files in Xcode editor.

Build the project

Press Cmd+B to build without running.

Run on device

Press Cmd+R to build and run on selected device/simulator.

Debugging

Console: View print() and NSLog() output in Xcode console
Breakpoints: Click line numbers to add breakpoints
View hierarchy: Use Debug View Hierarchy tool
Network: Use Network Link Conditioner for testing slow connections

Testing on Simulator

Run in iOS Simulator for quick testing:

Select simulator from device menu
Click Run
Simulator launches automatically

Simulators are useful for UI testing, but use real devices for accurate video playback performance testing.

Building for Distribution

Archive for TestFlight/App Store

Select Generic iOS Device

In device selector, choose Any iOS Device (arm64).

Create archive

Select Product > Archive from menu.Wait for build to complete.

Distribute archive

In Organizer window:

Select your archive
Click Distribute App
Choose distribution method:
- TestFlight & App Store for beta/release
- Ad Hoc for limited device distribution
- Enterprise for internal apps
Follow prompts to upload or export

Export IPA File

For manual distribution:

Archive the project (steps above)
Select Export instead of upload
Choose Development or Ad Hoc
Select signing certificate
Export IPA file

Install IPA using:

Xcode: Window > Devices and Simulators
Third-party tools like Apple Configurator

Troubleshooting

Code signing failed

Solutions:

Verify you’re signed in to Xcode with your Apple ID:
- Xcode > Settings > Accounts
Change Bundle Identifier to unique value
Select correct team in Signing & Capabilities
For free accounts, use automatic signing for development

Device not appearing in device list

Solutions:

Unlock your iOS device
Trust the computer when prompted
Reconnect USB cable
Open Window > Devices and Simulators to troubleshoot

App crashes on launch

Debugging steps:

Check Xcode console for crash logs
Verify server URL is reachable from device
Check Info.plist for correct permissions
Ensure iOS version meets minimum requirement (iOS 16+)

Videos won't play

Check:

Network connectivity between device and server
Server is serving MP4 files (not transcoding to HLS)
HTTP access is allowed (check App Transport Security)
Test server URL in Safari on device first

Solution: Verify with test URL:

// Test in Safari
http://your-server:5176/api/folder/ping

watchOS app won't build

Solutions:

Install watchOS platform: Xcode > Settings > Components
Ensure Apple Watch is paired with iPhone
Update watchOS to 10.6 or later
Check signing for both iOS and watchOS targets

HTTP connections blocked

Solution: Update Info.plist to allow your server domain:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>your-server.local</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
        </dict>
    </dict>
</dict>

Performance Optimization

Video Preloading

The app preloads upcoming videos:

// Preload configuration
let preloadCount = 2  // Number of videos to preload
let bufferDuration = 10.0  // Seconds of buffer

Adjust these values in the source code for your use case.

Memory Management

Automatic cleanup of unused AVPlayerItem instances
Cache limits for watchOS app
Efficient thumbnail loading

Network Optimization

Range request support for seeking
HEAD request optimization
Persistent connections

Publishing to App Store

To submit EmbyTok to the App Store:

Enroll in Apple Developer Program

Required for App Store distribution ($99/year).

Create App Store listing

In App Store Connect:

Create new app
Fill in app information
Add screenshots and descriptions
Set pricing and availability

Archive and upload

Follow “Building for Distribution” steps above to upload build.

Submit for review

Complete all required information and submit for Apple review.

Ensure your app complies with App Store Review Guidelines, especially regarding content and server connections.

Next Steps

Android App

Build Android version with Capacitor

Configuration

Configure Emby/Folder servers

iOS Development

Extend iOS app features

Folder Server

Set up folder server for iOS app

Get Started

Installation

Core Features

Configuration

Guides

​Overview

​System Requirements

Development Mac

Target Devices

Apple ID

watchOS (optional)

​Installation Steps

​Building watchOS App (Optional)

​Network Configuration

​App Transport Security

​Connecting to Servers

​Using the iOS App

​Video Playback Features

​AVPlayer Integration

​Preloading and Buffering

​Cache Management (watchOS)

​Xcode Project Structure

​Development Workflow

​Making Code Changes

​Debugging

​Testing on Simulator

​Building for Distribution

​Archive for TestFlight/App Store

​Export IPA File

​Troubleshooting

​Performance Optimization

​Video Preloading

​Memory Management

​Network Optimization

​Publishing to App Store

​Next Steps

Android App

Configuration

iOS Development

Folder Server

Build docs developers (and LLMs) love

Overview

System Requirements

Installation Steps

Building watchOS App (Optional)

Network Configuration

App Transport Security

Connecting to Servers

Using the iOS App

Video Playback Features

AVPlayer Integration

Preloading and Buffering

Cache Management (watchOS)

Xcode Project Structure

Development Workflow

Making Code Changes

Debugging

Testing on Simulator

Building for Distribution

Archive for TestFlight/App Store

Export IPA File

Troubleshooting

Performance Optimization

Video Preloading

Memory Management

Network Optimization

Publishing to App Store

Next Steps