ffmpeg-kit/apple/README.md

# FFmpegKit for iOS, macOS and tvOS

### 1. Features
#### 1.1 iOS
- Supports `iOS SDK 12.1+` on Main releases and `iOS SDK 10+` 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 shared `frameworks` and `xcframeworks`

#### 1.2 macOS
- Supports `macOS SDK 10.15+` on Main releases and `macOS SDK 10.12+` on LTS releases
- Includes `arm64` and `x86_64` architectures
- Objective-C API
- Camera access
- `ARC` enabled library
- Built with `-fembed-bitcode` flag
- Creates shared `frameworks` and `xcframeworks`

#### 1.3 tvOS
- Supports `tvOS SDK 11.0+` on Main releases and `tvOS SDK 10.0+` on LTS releases
- Includes `arm64`, `arm64-simulator` and `x86_64` architectures
- Objective-C API
- `ARC` enabled library
- Built with `-fembed-bitcode` flag
- Creates shared `frameworks` and `xcframeworks`

### 2. Building

Run `ios.sh`/`macos.sh`/`tvos.sh` inside the project root to build `ffmpeg-kit` and `ffmpeg` shared 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 8.0** or later
- **iOS SDK 10** or later
- **Command Line Tools**

##### 2.1.2 macOS

- **Xcode 8.0** or later
- **macOS SDK 10.12** or later
- **Command Line Tools**

##### 2.1.3 tvOS

- **Xcode 8.0** or later
- **tvOS SDK 10.0** 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 gettext 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.
- `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.
- `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.

### 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](https://github.com/arthenica/ffmpeg-kit).

    - iOS
    ```yaml
    pod 'ffmpeg-kit-ios-full', '~> 4.5.1'
    ```

    - macOS
    ```yaml
    pod 'ffmpeg-kit-macos-full', '~> 4.5.1'
    ```

    - tvOS
    ```yaml
    pod 'ffmpeg-kit-tvos-full', '~> 4.5.1'
    ```

2. Execute synchronous `FFmpeg` commands.

    ```objectivec
    #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.

    ```objectivec
    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.

    ```objectivec
    FFmpegSession* session = [FFmpegKit executeAsync:@"-i file1.mp4 -c:v mpeg4 file2.mp4" withCompleteCallback:^(FFmpegSession* 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

    ```objectivec
    FFprobeSession *session = [FFprobeKit execute:ffprobeCommand];

    if ([ReturnCode isSuccess:[session getReturnCode]]) {
        NSLog(@"Command failed. Please check output for the details.");
    }
    ```

   - Asynchronous

    ```objectivec
    [FFprobeKit executeAsync:ffmpegCommand withCompleteCallback:^(FFprobeSession* session) {

        CALLED WHEN SESSION IS EXECUTED

    }];
    ```

6. Get media information for a file.

    ```objectivec
    MediaInformationSession *mediaInformation = [FFprobeKit getMediaInformation:"<file path or uri>"];
    MediaInformation *mediaInformation =[mediaInformation getMediaInformation];
    ```

7. Stop ongoing `FFmpeg` operations.

   - Stop all executions
       ```objectivec
       [FFmpegKit cancel];
       ```
   - Stop a specific session
       ```objectivec
       [FFmpegKit cancel:sessionId];
       ```

8. Get previous `FFmpeg` and `FFprobe` sessions from session history.

    ```objectivec
    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.

    - Session type specific Complete Callbacks, called when an async session has been completed

        ```objectivec
        [FFmpegKitConfig enableFFmpegSessionCompleteCallback:^(FFmpegSession* session) {
            ...
        }];

        [FFmpegKitConfig enableFFprobeSessionCompleteCallback:^(FFprobeSession* session) {
            ...
        }];

        [FFmpegKitConfig enableMediaInformationSessionCompleteCallback:^(MediaInformationSession* session) {
            ...
        }];
        ```

    - Log Callback, called when a session generates logs

        ```objectivec
        [FFmpegKitConfig enableLogCallback:^(Log *log) {
            ...
        }];
        ```

    - Statistics Callback, called when a session generates statistics

        ```objectivec
        [FFmpegKitConfig enableStatisticsCallback:^(Statistics *statistics) {
            ...
        }];
        ```

10. Ignore the handling of a signal. Required by `Mono` and frameworks that use `Mono`, e.g. `Unity` and `Xamarin`.

    ```objectivec
    [FFmpegKitConfig ignoreSignal:SIGXCPU];
    ```

11. Register system fonts and custom font directories.

    ```objectivec
    [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](https://github.com/arthenica/ffmpeg-kit-test) project.