ffmpeg-kit/apple
2021-09-15 15:54:31 +01:00
..
m4 update external library scripts 2021-01-09 16:03:59 +00:00
src StreamInformation getFullCodec method renamed as getCodecLong 2021-09-15 15:54:31 +01:00
.gitignore update external library scripts 2021-01-09 16:03:59 +00:00
aclocal.m4 refactor api 2021-02-14 22:59:48 +00:00
ar-lib update external library scripts 2021-01-09 16:03:59 +00:00
autogen.sh update external library scripts 2021-01-09 16:03:59 +00:00
compile update external library scripts 2021-01-09 16:03:59 +00:00
config.guess refactor api 2021-02-14 22:59:48 +00:00
config.sub refactor api 2021-02-14 22:59:48 +00:00
configure refactor api 2021-02-14 22:59:48 +00:00
configure.ac update external library scripts 2021-01-09 16:03:59 +00:00
depcomp update external library scripts 2021-01-09 16:03:59 +00:00
Doxyfile update documentation 2021-03-03 18:59:41 +00:00
install-sh refactor api 2021-02-14 22:59:48 +00:00
libtool update external library scripts 2021-01-09 16:03:59 +00:00
ltmain.sh update external library scripts 2021-01-09 16:03:59 +00:00
Makefile.am update external library scripts 2021-01-09 16:03:59 +00:00
Makefile.in refactor api 2021-02-14 22:59:48 +00:00
missing update external library scripts 2021-01-09 16:03:59 +00:00
README.md update set font directory list example on apple readme 2021-04-03 19:17:42 +01:00

FFmpegKit for iOS, macOS and tvOS

1. Features

1.1 iOS

  • Supports iOS SDK 12.1+ on Main releases and iOS SDK 9.3+ on LTS releases
  • Includes armv7, armv7s, arm64, arm64-simulator, arm64e, i386, x86_64, x86_64-mac-catalyst and arm64-mac-catalyst architectures
  • Objective-C API
  • Camera access
  • ARC enabled library
  • Built with -fembed-bitcode flag
  • Creates static frameworks, static xcframeworks and static universal (fat) libraries (.a)

1.2 macOS

  • Supports macOS SDK 10.15+ on Main releases and macOS SDK 10.11+ on LTS releases
  • Includes arm64 and x86_64 architectures
  • Objective-C API
  • Camera access
  • ARC enabled library
  • Built with -fembed-bitcode flag
  • Creates static frameworks, static xcframeworks and static universal (fat) libraries (.a)

1.3 tvOS

  • Supports tvOS SDK 10.2+ on Main releases and tvOS SDK 9.2+ on LTS releases
  • Includes arm64, arm64-simulator and x86_64 architectures
  • Objective-C API
  • ARC enabled library
  • Built with -fembed-bitcode flag
  • Creates static frameworks, static xcframeworks and static universal (fat) libraries (.a)

2. Building

Run ios.sh/macos.sh/tvos.sh at project root directory to build ffmpeg-kit and ffmpeg static libraries for a platform.

Optionally, use apple.sh to combine bundles created by these three scripts in a single bundle.

Please note that FFmpegKit project repository includes the source code of FFmpegKit only. ios.sh, macos.sh and tvos.sh need network connectivity and internet access to github.com in order to download the source code of FFmpeg and external libraries enabled.

2.1 Prerequisites

ios.sh, macos.sh and tvos.sh require the following tools and packages.

2.1.1 iOS
  • Xcode 7.3.1 or later
  • iOS SDK 9.3 or later
  • Command Line Tools
2.1.2 macOS
  • Xcode 7.3.1 or later
  • macOS SDK 10.11 or later
  • Command Line Tools
2.1.3 tvOS
  • Xcode 7.3.1 or later
  • tvOS SDK 9.2 or later
  • Command Line Tools
2.1.4 Packages

Use your package manager (brew, etc.) to install the following packages.

autoconf automake libtool pkg-config curl cmake gcc gperf texinfo yasm nasm bison autogen git wget autopoint meson ninja

2.2 Options

Use --enable-<library name> flag to support additional external or system libraries and --disable-<architecture name> to disable architectures you don't want to build.

./ios.sh --enable-fontconfig --disable-armv7

./macos.sh --enable-freetype --enable-macos-avfoundation --disable-arm64

./tv.sh --enable-dav1d --enable-libvpx --disable-arm64-simulator

Run --help to see all available build options.

2.3 LTS Binaries

Use --lts option to build lts binaries for each architecture.

2.4 Build Output

All libraries created can be found under the prebuilt directory.

  • iOS xcframeworks for Main builds are located under the bundle-apple-xcframework-ios folder.
  • macOS xcframeworks for Main builds are located under the bundle-apple-xcframework-macos folder.
  • tvOS xcframeworks for Main builds are located under the bundle-apple-xcframework-tvos folder.
  • iOS frameworks for Main builds are located under the bundle-apple-framework-ios folder.
  • iOS frameworks for LTS builds are located under the bundle-apple-framework-ios-lts folder.
  • iOS universal (fat) libraries (.a) for LTS builds are located under the bundle-apple-universal-ios-lts folder.
  • macOS frameworks for Main builds are located under the bundle-apple-framework-macos folder.
  • macOS frameworks for LTS builds are located under the bundle-apple-framework-macos-lts folder.
  • macOS universal (fat) libraries (.a) for LTS builds are located under the bundle-apple-universal-macos-lts folder.
  • tvOS frameworks for Main builds are located under the bundle-apple-framework-tvos folder.
  • tvOS frameworks for LTS builds are located under the bundle-apple-framework-tvos-lts folder.
  • tvOS universal (fat) libraries (.a) for LTS builds are located under the bundle-apple-universal-tvos-lts folder.

3. Using

3.1 Objective API

  1. Add FFmpegKit dependency to your Podfile in ffmpeg-kit-<platform>-<package name> pattern. Use one of the FFmpegKit package names given in the project README.

    • iOS
    pod 'ffmpeg-kit-ios-full', '~> 4.4.LTS'
    
    • macOS
    pod 'ffmpeg-kit-macos-full', '~> 4.4.LTS'
    
    • tvOS
    pod 'ffmpeg-kit-tvos-full', '~> 4.4.LTS'
    
  2. Execute synchronous FFmpeg commands.

    #include <ffmpegkit/FFmpegKit.h>
    
    FFmpegSession *session = [FFmpegKit execute:@"-i file1.mp4 -c:v mpeg4 file2.mp4"];
    ReturnCode *returnCode = [session getReturnCode];
    if ([ReturnCode isSuccess:returnCode]) {
    
        // SUCCESS
    
    } else if ([ReturnCode isCancel:returnCode]) {
    
        // CANCEL
    
    } else {
    
        // FAILURE
        NSLog(@"Command failed with state %@ and rc %@.%@", [FFmpegKitConfig sessionStateToString:[session getState]], returnCode, [session getFailStackTrace]);
    
    }
    
  3. Each execute call (sync or async) creates a new session. Access every detail about your execution from the session created.

    FFmpegSession *session = [FFmpegKit execute:@"-i file1.mp4 -c:v mpeg4 file2.mp4"];
    
    // Unique session id created for this execution
    long sessionId = [session getSessionId];
    
    // Command arguments as a single string
    NSString *command = [session getCommand];
    
    // Command arguments
    NSArray *arguments = [session getArguments];
    
    // State of the execution. Shows whether it is still running or completed
    SessionState state = [session getState];
    
    // Return code for completed sessions. Will be null if session is still running or ends with a failure
    ReturnCode *returnCode = [session getReturnCode];
    
    NSDate *startTime =[session getStartTime];
    NSDate *endTime =[session getEndTime];
    long duration =[session getDuration];
    
    // Console output generated for this execution
    NSString *output = [session getOutput];
    
    // The stack trace if FFmpegKit fails to run a command
    NSString *failStackTrace = [session getFailStackTrace];
    
    // The list of logs generated for this execution
    NSArray *logs = [session getLogs];
    
    // The list of statistics generated for this execution
    NSArray *statistics = [session getStatistics];
    
  4. Execute asynchronous FFmpeg commands by providing session specific execute/log/session callbacks.

    id<Session> session = [FFmpegKit executeAsync:@"-i file1.mp4 -c:v mpeg4 file2.mp4" withExecuteCallback:^(id<Session> session){
        SessionState state = [session getState];
        ReturnCode *returnCode = [session getReturnCode];
    
        // CALLED WHEN SESSION IS EXECUTED
    
        NSLog(@"FFmpeg process exited with state %@ and rc %@.%@", [FFmpegKitConfig sessionStateToString:state], returnCode, [session getFailStackTrace]);
    
    } withLogCallback:^(Log *log) {
    
        // CALLED WHEN SESSION PRINTS LOGS
    
    } withStatisticsCallback:^(Statistics *statistics) {
    
        // CALLED WHEN SESSION GENERATES STATISTICS
    
    }];
    
  5. Execute FFprobe commands.

    • Synchronous
    FFprobeSession *session = [FFprobeKit execute:ffprobeCommand];
    
    if ([ReturnCode isSuccess:[session getReturnCode]]) {
        NSLog(@"Command failed. Please check output for the details.");
    }
    
    • Asynchronous
    [FFprobeKit executeAsync:ffmpegCommand withExecuteCallback:^(id<Session> session) {
    
        CALLED WHEN SESSION IS EXECUTED
    
    }];
    
  6. Get media information for a file.

    MediaInformationSession *mediaInformation = [FFprobeKit getMediaInformation:"<file path or uri>"];
    MediaInformation *mediaInformation =[mediaInformation getMediaInformation];
    
  7. Stop ongoing FFmpeg operations.

    • Stop all executions
      [FFmpegKit cancel];
      
    • Stop a specific session
      [FFmpegKit cancel:sessionId];
      
  8. Get previous FFmpeg and FFprobe sessions from session history.

    NSArray* sessions = [FFmpegKitConfig getSessions];
    for (int i = 0; i < [sessions count]; i++) {
        id<Session> session = [sessions objectAtIndex:i];
        NSLog(@"Session %d = id: %ld, startTime: %@, duration: %ld, state:%@, returnCode:%@.\n",
            i,
            [session getSessionId],
            [session getStartTime],
            [session getDuration],
            [FFmpegKitConfig sessionStateToString:[session getState]],
            [session getReturnCode]);
    }
    
  9. Enable global callbacks.

    • Execute Callback, called when an async execution is ended

      [FFmpegKitConfig enableExecuteCallback:^(id<Session> session) {
          ...
      }];
      
    • Log Callback, called when a session generates logs

      [FFmpegKitConfig enableLogCallback:^(Log *log) {
          ...
      }];
      
    • Statistics Callback, called when a session generates statistics

      [FFmpegKitConfig enableStatisticsCallback:^(Statistics *statistics) {
          ...
      }];
      
  10. Ignore the handling of a signal. Required by Mono and frameworks that use Mono, e.g. Unity and Xamarin.

    [FFmpegKitConfig ignoreSignal:SIGXCPU];
    
  11. Register system fonts and custom font directories.

    [FFmpegKitConfig setFontDirectoryList:[NSArray arrayWithObjects:@"/System/Library/Fonts", @"<folder with fonts>", nil] with:nil];
    

4. Test Application

You can see how FFmpegKit is used inside an application by running iOS, macOS and tvOS test applications developed under the FFmpegKit Test project.