← Back to App Dashboard
🎬

IINA Advanced Maintenance Guide

The elite modern media engine for macOS. Hardware acceleration overrides for the mpv kernel pipeline, audio driver latency synchronization, and total cache purge routines.

1. Production Installation Command

bash
brew install --cask iina

2. Deep-Dive Maintenance & CLI Core Tuning Sheet

Target Operational Action / Hotkey Terminal Command Syntax / Core Tweak
Toggle Playback State
Pause or resume the active video buffer pipeline instantly.
Spacebar
Summon Technical Inspector
Expose real-time hardware decoding metrics, current bitrates, and dropped frames.
⌘ + I
Stream Dynamic Network URL
Force-feed a raw web video link directly into the high-performance localized player window.
open -a IINA "https://example.com"
Flush Local Watch History
Completely wipe out the application's historical cache of recent files and last window states via system defaults.
defaults delete com.colliderli.iina history && defaults delete com.colliderli.iina recentDocuments
Purge Subtitle & Thumbnail Cache
Clear out broken intermediate font remnants, network logs, and downloaded open-subtitles data.
rm -rf ~/Library/Caches/com.colliderli.iina/*
Complete Settings Resets
Kill the operational interface runtime and completely clear out the configuration plist trees to fix bugs.
pkill -9 IINA && defaults delete com.colliderli.iina

3. Critical Troubleshooting & Crash Base

🚨 Error #1: 4K HDR Playback Jitter (Dropped Rendering Frames)

Root Cause: Software decoding fallbacks cause massive CPU spikes on heavy bitrates. Force the underlying mpv kernel to exclusively utilize native Apple Silicon VideoToolbox hardware acceleration protocols:

bash
defaults write com.colliderli.iina mpv.hwdec auto

🚨 Error #2: Audio-Video Desynchronization on External Sound Cards

Root Cause: macOS CoreAudio changes buffering parameters on Bluetooth devices or professional USB interfaces. Force the player to rebuild its strict timeline clock mapping:

bash
defaults write com.colliderli.iina mpv.audio-delay 0.0 && killall IINA

🚨 Error #3: Picture-in-Picture (PiP) Window Disappears Under Desktop Layers

Root Cause: macOS window manager states occasionally fail to lock the detached overlay focus above full-screen spaces. Re-register the interface layer layer priorities:

bash
defaults write com.colliderli.iina pipOntop -bool true

🚨 Error #4: Broken Core Plugins (Infinite Crash Loops on Boot)

Root Cause: Corrupted third-party JavaScript scripts or custom themes lock up the initial layout runtime engine. Forcefully wipe out the entire user data application support matrix:

bash
rm -rf ~/Library/Application\ Support/com.colliderli.iina/