FSPlayer

Stargazers repo roster for @debugly/fsplayer

FSPlayer is the actively-maintained successor to ijkplayer. It keeps the proven ijkplayer architecture while replacing its aging foundation with a modern one: FFmpeg 8, Metal / Vulkan rendering, hardware-decode hot-switching, and first-class support for HDR, Dolby Vision, Blu-ray/ISO, and rich subtitle effects.

🇨🇳 中文文档见 README.md

Why FSPlayer over ijkplayer

ijkplayer has been effectively unmaintained for years — its last release (k0.8.8) is from 2018. It ships FFmpeg 4.0 (2021). Renders through OpenGL ES 2.0, and its own README lists native subtitle rendering and avfilter support as explicitly not on plan.

FSPlayer keeps the same architecture you know, and moves the stack forward:

	ijkplayer	FSPlayer
Maintenance	Stalled — last release 2018, last commit 2021	Active — updated monthly
FFmpeg	4.0	8.1.2
Platforms	Android, iOS	Android, iOS, macOS, tvOS,
Video output	OpenGL ES 2.0	Metal (iOS/macOS/tvOS) · Vulkan (Android)
4K / HDR / HDR10+ / Dolby Vision	✗	✓
Native subtitle rendering	✗ (explicitly not on plan)	✓ — ASS effects, text + bitmap subs
Blu-ray / ISO / BDMV	✗	✓ — incl. over network
avfilter / video filters	✗ (explicitly not on plan)	✓ — e.g. software deinterlacing
HW-decode hot switch	✗	✓ — no player restart needed
Distribution	jcenter (dead) / manual	SPM + CocoaPods · Maven Central (Android)
License	LGPLv2.1+	LGPLv2.1+

Already on ijkplayer? Migration is straightforward — see the migration guide.

FSPlayer All Features

• FFmpeg 8.1.2
• Pass-through of FFmpeg options
• Download speed & preload progress reporting
• Media info (audio sample rate / channels / duration; video width / height / fps / duration)
• First-frame decode & render timing
• Protocols: file, http, https, udp, rtmp, rtp, rtsp, bluray, smb, ftp, …
• HTTP tuning: timeout, retry, User-Agent, Cookie, Referer, Origin (and pass-through to TS requests for m3u8)
• HLS live & VOD
• AV1 and uavs3 decoders
• Embedded cover art for audio playback
• Image playback (incl. animated WebP)
• Accurate seeking
• Hardware / software decoding, switchable without restart
• Multiple concurrent instances
• Re-seek after EOF
• Fast start for file protocol seeks
• Encrypted A/V playback (e.g. AES-128 HLS)
• Powerful subtitles
  • Text subtitles (srt / vtt / ass)
  • Bitmap subtitles (dvbsub / dvdsub / pgssub / idx+sub)
  • Embedded and external
  • Subtitle delay
  • ASS effects
  • Text subtitle styling
• Loop playback
• Audio track switching & track delay
• Snapshot (jpg, png, tiff)
• Display aspect ratio, rotation (0/90/180/270), horizontal & vertical mirror
• Video background color (default black)
• Saturation / brightness / contrast
• Render one frame to multiple views
• Real-time PCM access
• Custom render view & custom audio renderer
• 4K / HDR / HDR10 / HDR10+ / Dolby Vision (Pro adds Dolby Vision P5)
• Smart ISO detection (bluray / DVD / regular video)
• No pixelation on MPEG-TS fast-forward
• Network playback of ISO images and BDMV folders
• Force a channel on stereo audio
• Access the currently displayed video frame
• Video recording (iOS saves to Photos)
• Buffer progress notifications
• Async destroy (safe even without calling shutdown)
• Optional player-controlled AudioSession
• Smoother view rotation animation
• Tile-grid HEIC playback
• Gaussian blur background

Latest additions

• HDR display brightens the HDR screen
• Playable & seekable when audio ends before video
• Video filters with software deinterlacing
• Synchronous destroy (async by default)

Under investigation

• AV1 hardware decode (stable on most, some files still crash)
• Live playback / timeshift
• Variable playback rate with pitch correction
• Transparent video
• Picture-in-picture

Build environment

• macOS Tahoe (26.5)
• Xcode 26.6 (17F113)
• Android NDK 27.3

Minimum platform	Architectures
iOS 12.0	arm64, arm64_simulator, x86_64_simulator
macOS 10.14	arm64, x86_64
tvOS 12.0	arm64, arm64_simulator, x86_64_simulator
Android 7.0 (API 24)	arm64-v8a, armeabi-v7a

Changelog

• CHANGELOG.md

Integration

FSPlayer is free and released under LGPLv2.1+. If it's useful to you, buy the author a coffee.

• Swift Package Manager: FSPlayer-SPM
• CocoaPods:

pod "FSPlayer", :podspec => 'https://github.com/debugly/fsplayer/releases/download/1.1.1/FSPlayer.spec.json'

• Android (Gradle, Maven Central):

dependencies {
    implementation 'io.github.debugly:fsplayer:1.1.1'
}

Usage

Apple

FSOptions *options = [FSOptions optionsByDefault];
self.player = [[FSPlayer alloc] initWithContent:url options:options];

NSView <FSVideoRenderingProtocol>* playerView = self.player.view;
playerView.frame = self.playerContainer.bounds;
playerView.autoresizingMask = NSViewWidthSizable | NSViewHeightSizable;
[self.playerContainer addSubview:playerView positioned:NSWindowBelow relativeTo:self.playerCtrlPanel];

self.player.shouldAutoplay = YES;
[self.player prepareToPlay];

Android

The Android build is an AAR. FSPlayer implements IMediaPlayer directly (the ijkplayer-style setDataSource / prepareAsync / start lifecycle), so hand it a SurfaceHolder and it renders there.

FSPlayer player = new FSPlayer();
// hardware / software decoding, same option semantics as ijkplayer
player.setOption(FSPlayer.OPT_CATEGORY_PLAYER, "mediacodec", 1);
player.setDisplay(surfaceView.getHolder());   // or setSurface(surface)

player.setDataSource(context, uri);
player.setOnPreparedListener(mp -> mp.start());
player.prepareAsync();

Call release() when done. To switch media source on a live instance use reset(), which tears down and recreates the native player. To check whether hardware or software decoding is in use, look at getVideoDecoder() (FFP_PROPV_DECODER_MEDIACODEC means hardware).

Full documentation.

Building from source

The source is fully open; build the framework (Apple) or AAR (Android) yourself:

# iOS
./FFToolChain/main.sh install -p ios -l 'ass ffmpeg'
./examples/ios/build-framework.sh
# macOS
./FFToolChain/main.sh install -p macos -l 'ass ffmpeg'
./examples/macos/build-framework.sh
# tvOS
./FFToolChain/main.sh install -p tvos -l 'ass ffmpeg'
./examples/tvos/build-framework.sh
# Android
./FFToolChain/main.sh install -p android -l 'ass ffmpeg'
cd android && ./gradlew :fsplayer:assembleRelease

FSPlayer-Pro

A drop-in dynamic library on top of FSPlayer with extra capabilities:

• Dolby Vision P5
• HLS VOD play-while-cache (seeking back to cached content costs no traffic and starts faster)
• Seamless audio-track switching (no reload / no brief silence or black frame)
• Seamless quality switching
• Multi-x faster first-frame and seek start for network ISO / BDMV playback

Contact: debugly@icloud.com