IINA Deployment & Usage Guide

A comprehensive guide for building, configuring, and deploying IINA, the modern macOS video player.

Prerequisites

System Requirements

• macOS: Version 10.15 (Catalina) or later
• Hardware: Apple Silicon (ARM64) or Intel (x86_64) Mac
• Storage: ~2GB free space for Xcode and dependencies

Required Tools

• Xcode: Latest public version from the Mac App Store (IINA may not build with beta or older versions)
• Git: For cloning the repository
• Command Line Tools: xcode-select --install

Optional Dependencies (for manual mpv builds)

• Homebrew or MacPorts: For building mpv from source
• Ruby: For running build scripts (included with macOS)

API Credentials (Optional)

• OpenSubtitles.com account: Required for online subtitle search features (migrate from opensubtitles.org if needed)

Installation

1. Clone the Repository

git clone https://github.com/iina/iina.git
cd iina

2. Choose Build Method

Option A: Pre-compiled Libraries (Recommended)

Download pre-built universal binaries:

./other/download_libs.sh

Architecture-specific builds: Edit other/download_libs.sh to change the URL to https://iina.io/dylibs/${ARCH}/filelist.txt where ARCH is arm64, x86_64, or universal (default).

Version matching: For older IINA versions, use the corresponding dylibs URL (e.g., https://iina.io/dylibs/1.2.0/universal/filelist.txt).

Option B: Build mpv Manually

Using Homebrew:

brew tap iina/homebrew-mpv-iina
brew install mpv-iina

Using MacPorts:

port install mpv +uchardet -bundle -rubberband configure.args="--enable-libmpv-shared --enable-lua --enable-libarchive --enable-libbluray --disable-swift --disable-rubberband"

Copy headers and generate bindings:

# Copy mpv/FFmpeg headers from Homebrew/MacPorts to deps/include/
# Then regenerate Swift bindings:
./other/parse_doc.rb
cp other/MPVOption.swift other/MPVCommand.swift other/MPVProperty.swift iina/

# Deploy libraries
./other/change_lib_dependencies.rb "$(brew --prefix)" "$(brew --prefix mpv-iina)/lib/libmpv.dylib"

Configuration

OpenSubtitles API Setup

For online subtitle search functionality:

1. Create an account at opensubtitles.com (migrate from opensubtitles.org if you have an existing account)
2. Generate API credentials in your account settings
3. Configure credentials in IINA preferences under Subtitles > Online Search

mpv Configuration

IINA respects standard mpv configuration files:

• Config location: ~/.config/mpv/mpv.conf
• Scripts: ~/.config/mpv/scripts/
• Lua scripts: Supported for advanced customization

Custom Key Bindings

Edit ~/.config/mpv/input.conf or use IINA's preferences window (Preferences > Key Bindings) to customize:

• Keyboard shortcuts
• Mouse gestures
• Trackpad gestures
• Force Touch actions

Environment Variables

For development debugging:

export IINA_DEBUG=1  # Enable verbose logging

Build & Run

Development Build

1. Open Xcode project:

   open iina.xcodeproj
   

2. Configure signing (if building manually):

   • Select the "iina" target
   • Go to Signing & Capabilities
   • Set your Team and Bundle Identifier

3. Build and run:

   • Press Cmd+R or click Product > Run
   • Select target device (My Mac)

Production Archive

1. Select scheme: Choose "iina" > "Any Mac (Apple Silicon, Intel)"
2. Archive: Product > Archive
3. Distribute:
   • Select the archive in Organizer
   • Click Distribute App
   • Choose Copy App (for local testing) or Developer ID (for distribution)

Command Line Tool

IINA includes a command line tool iina-cli:

# Install the CLI tool from IINA preferences
# Or use directly:
/Applications/IINA.app/Contents/MacOS/iina-cli <file>

Deployment

Distribution Methods

1. Direct Distribution (Recommended)

Create a signed and notarized DMG for distribution outside the App Store:

# Create app bundle (already done via Archive)
# Sign with Developer ID
codesign --force --deep --sign "Developer ID Application: Your Name" IINA.app

# Notarize (requires Apple Developer account)
xcrun altool --notarize-app --primary-bundle-id "com.colliderli.iina" \
  --username "your@email.com" --password "@keychain:AC_PASSWORD" \
  --file IINA.dmg

# Staple ticket
xcrun stapler staple IINA.app

2. GitHub Releases

• Upload the notarized .app bundle or .dmg to GitHub Releases
• Include filelist.txt and dylibs for the version in https://iina.io/dylibs/

3. Homebrew Cask (End User Installation)

Users can install stable releases via:

brew install --cask iina

Note: IINA is not typically distributed via the Mac App Store due to GPL licensing constraints with mpv.

Browser Extensions

Deploy companion browser extensions:

• Safari extension included in the app bundle
• Chrome/Firefox extensions available separately for opening videos in IINA

Troubleshooting

Build Issues

"IINA may not build if you use any other version"

• Solution: Update Xcode to the latest public release from the App Store, not a beta version.

Missing dylib files or architecture mismatches

• Symptom: Library not loaded errors
• Solution: Ensure you downloaded the correct architecture binaries. For Apple Silicon Macs building for both architectures, use universal binaries:

  ./other/download_libs.sh
  

Header file version mismatch

• Symptom: API errors in MPVProperty.swift
• Solution: When building mpv manually, ensure header files in deps/include/ match the dylib version exactly. Copy headers from the same Homebrew/MacPorts installation.

MPVOption.swift generation fails

• Solution: Run other/parse_doc.rb to regenerate bindings after updating mpv:

  cd other
  ruby parse_doc.rb
  cp MPVOption.swift MPVCommand.swift MPVProperty.swift ../iina/
  

Runtime Issues

OpenSubtitles login fails

• Cause: Migration from opensubtitles.org to opensubtitles.com
• Solution: Visit opensubtitles.com/users/import to migrate your account and set a new password.

Touch Bar/Force Touch not working

• Solution: Ensure "Enable Touch Bar support" is checked in Preferences > UI and that IINA has Accessibility permissions in System Preferences > Security & Privacy.

Subtitles not loading automatically

• Solution: Check Preferences > Subtitles for "Auto load" settings. IINA matches subtitles by filename (e.g., video.mp4 + video.srt).

Development Debugging

View controller not loading

• Check nibName definitions in view controllers (e.g., PlaylistViewController, QuickSettingViewController) match XIB filenames.

Menu actions not responding

• Verify menu items are properly connected to MenuController.swift and that key action strings match mpv command syntax.

Library deployment issues

• If using custom mpv builds, ensure other/change_lib_dependencies.rb was run to copy all dependencies to deps/lib/ and that all .dylib files are added to the "Copy Dylibs" and "Link Binary With Libraries" build phases.