...
This commit is contained in:
@@ -0,0 +1,285 @@
|
||||
# FFmpegKit for Linux
|
||||
|
||||
### 1. Features
|
||||
- Provides a `C++` API with `c++11`
|
||||
- Includes `x86_64` architecture
|
||||
- Builds shared native libraries (.so)
|
||||
- Prebuilt binaries not published
|
||||
|
||||
### 2. Building
|
||||
|
||||
Run `linux.sh` at project root directory to build `ffmpeg-kit` and `ffmpeg` shared libraries.
|
||||
|
||||
Please note that `FFmpegKit` project repository includes the source code of `FFmpegKit` only. `linux.sh` needs
|
||||
network connectivity and internet access to `github.com` in order to download the source code of `FFmpeg` and
|
||||
external libraries enabled.
|
||||
|
||||
#### 2.1 Prerequisites
|
||||
|
||||
`linux.sh` requires the following packages.
|
||||
|
||||
##### 2.1.1 Packages
|
||||
|
||||
Use your package manager (apt, yum, dnf, etc.) to install the following packages.
|
||||
|
||||
Note that the names of the Linux packages vary from distribution to distribution. The names given below are
|
||||
valid for Debian/Ubuntu. Some packages may have a different name if you are on another distribution.
|
||||
|
||||
- The following packages are required by the build scripts.
|
||||
|
||||
```
|
||||
clang llvm lld libclang-14-dev libstdc++6 nasm autoconf automake libtool pkg-config curl git doxygen rapidjson-dev
|
||||
```
|
||||
|
||||
- These optional packages should be installed only if you want to build corresponding external libraries.
|
||||
|
||||
```
|
||||
cmake libasound2-dev libass-dev libfontconfig1-dev libfreetype-dev libfribidi-dev libgmp-dev libgnutls28-dev libmp3lame-dev libopencore-amrnb-dev libopencore-amrwb-dev libopus-dev librubberband-dev libsdl2-dev libshine-dev libsnappy-dev libsoxr-dev libspeex-dev libtesseract-dev libtheora-dev libtwolame-dev libva-dev libvidstab-dev libvorbis-dev libvo-amrwbenc-dev libvpx-dev libv4l-dev libwebp-dev libxml2-dev libxvidcore-dev libx265-dev meson ocl-icd-opencl-dev opencl-headers tcl zlib1g-dev groff gtk-doc-tools libtasn1
|
||||
```
|
||||
|
||||
#### 2.2 Options
|
||||
|
||||
Use `--enable-<library name>` flag to support additional external or system libraries.
|
||||
|
||||
```
|
||||
./linux.sh --enable-fontconfig
|
||||
```
|
||||
|
||||
Run `--help` to see all available build options.
|
||||
|
||||
#### 2.3 Build Output
|
||||
|
||||
All libraries created by `linux.sh` can be found under the `prebuilt` directory.
|
||||
|
||||
- Headers and libraries created for the `Main` builds are located under the `bundle-linux` folder.
|
||||
|
||||
### 3. Using
|
||||
|
||||
#### 3.1 C++ API
|
||||
|
||||
`FFmpegKit` doesn't publish any prebuilt `Linux` libraries, as it does for other platforms. Therefore, you need to
|
||||
manually build and import `FFmpegKit` libraries into your projects.
|
||||
|
||||
Then, you can use the following API methods to execute `FFmpeg` and `FFprobe` commands inside your application.
|
||||
|
||||
1. Execute synchronous `FFmpeg` commands.
|
||||
|
||||
```C++
|
||||
#include <FFmpegKit.h>
|
||||
#include <FFmpegKitConfig.h>
|
||||
|
||||
using namespace ffmpegkit;
|
||||
|
||||
auto session = FFmpegKit::execute("-i file1.mp4 -c:v mpeg4 file2.mp4");
|
||||
if (ReturnCode::isSuccess(session->getReturnCode())) {
|
||||
|
||||
// SUCCESS
|
||||
|
||||
} else if (ReturnCode::isCancel(session->getReturnCode())) {
|
||||
|
||||
// CANCEL
|
||||
|
||||
} else {
|
||||
|
||||
// FAILURE
|
||||
std::cout << "Command failed with state " << FFmpegKitConfig::sessionStateToString(session->getState()) << " and rc " << session->getReturnCode() << "." << session->getFailStackTrace() << std::endl;
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
2. Each `execute` call (sync or async) creates a new session. Access every detail about your execution from the
|
||||
session created.
|
||||
|
||||
```C++
|
||||
#include <FFmpegKit.h>
|
||||
#include <FFmpegKitConfig.h>
|
||||
|
||||
using namespace ffmpegkit;
|
||||
|
||||
auto 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
|
||||
auto command = session->getCommand();
|
||||
|
||||
// Command arguments
|
||||
auto 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
|
||||
auto returnCode = session->getReturnCode();
|
||||
|
||||
auto startTime = session->getStartTime();
|
||||
auto endTime = session->getEndTime();
|
||||
long duration = session->getDuration();
|
||||
|
||||
// Console output generated for this execution
|
||||
auto output = session->getOutput();
|
||||
|
||||
// The stack trace if FFmpegKit fails to run a command
|
||||
auto failStackTrace = session->getFailStackTrace();
|
||||
|
||||
// The list of logs generated for this execution
|
||||
auto logs = session->getLogs();
|
||||
|
||||
// The list of statistics generated for this execution
|
||||
auto statistics = session->getStatistics();
|
||||
```
|
||||
|
||||
3. Execute asynchronous `FFmpeg` commands by providing session specific `execute`/`log`/`session` callbacks.
|
||||
|
||||
```C++
|
||||
#include <FFmpegKit.h>
|
||||
#include <FFmpegKitConfig.h>
|
||||
|
||||
using namespace ffmpegkit;
|
||||
|
||||
FFmpegKit::executeAsync("-i file1.mp4 -c:v mpeg4 file2.mp4", [](auto session) {
|
||||
const auto state = session->getState();
|
||||
auto returnCode = session->getReturnCode();
|
||||
|
||||
// CALLED WHEN SESSION IS EXECUTED
|
||||
|
||||
std::cout << "FFmpeg process exited with state " << FFmpegKitConfig::sessionStateToString(state) << " and rc " << returnCode << "." << session->getFailStackTrace() << std::endl;
|
||||
}, [](auto log) {
|
||||
|
||||
// CALLED WHEN SESSION PRINTS LOGS
|
||||
|
||||
}, [](auto statistics) {
|
||||
|
||||
// CALLED WHEN SESSION GENERATES STATISTICS
|
||||
|
||||
});
|
||||
```
|
||||
|
||||
4. Execute `FFprobe` commands.
|
||||
|
||||
- Synchronous
|
||||
|
||||
```C++
|
||||
#include <FFprobeKit.h>
|
||||
#include <FFmpegKitConfig.h>
|
||||
|
||||
using namespace ffmpegkit;
|
||||
|
||||
auto session = FFprobeKit::execute(ffprobeCommand);
|
||||
|
||||
if (!ReturnCode::isSuccess(session->getReturnCode())) {
|
||||
std::cout << "Command failed. Please check output for the details." << std::endl;
|
||||
}
|
||||
```
|
||||
|
||||
- Asynchronous
|
||||
|
||||
```C++
|
||||
#include <FFprobeKit.h>
|
||||
#include <FFmpegKitConfig.h>
|
||||
|
||||
using namespace ffmpegkit;
|
||||
|
||||
FFprobeKit::executeAsync(ffprobeCommand, [](auto session) {
|
||||
|
||||
// CALLED WHEN SESSION IS EXECUTED
|
||||
|
||||
});
|
||||
```
|
||||
|
||||
5. Get media information for a file.
|
||||
|
||||
```C++
|
||||
#include <FFprobeKit.h>
|
||||
|
||||
using namespace ffmpegkit;
|
||||
|
||||
auto mediaInformation = FFprobeKit::getMediaInformation("<file path or uri>");
|
||||
mediaInformation->getMediaInformation();
|
||||
```
|
||||
|
||||
6. Stop ongoing `FFmpeg` operations.
|
||||
|
||||
- Stop all executions
|
||||
```C++
|
||||
FFmpegKit::cancel();
|
||||
```
|
||||
- Stop a specific session
|
||||
```C++
|
||||
FFmpegKit::cancel(sessionId);
|
||||
```
|
||||
|
||||
7. Get previous `FFmpeg` and `FFprobe` sessions from session history.
|
||||
|
||||
```C++
|
||||
#include <FFmpegKitConfig.h>
|
||||
|
||||
using namespace ffmpegkit;
|
||||
|
||||
auto sessions = FFmpegKitConfig::getSessions();
|
||||
int i = 0;
|
||||
std::for_each(sessions->begin(), sessions->end(), [](const auto session) {
|
||||
std::cout << "Session " << i++ << " = id:" << session->getSessionId() << ", startTime:" << session->getStartTime() << ", duration:" << session-> getDuration() << ", state:" << FFmpegKitConfig::sessionStateToString(session->getState()) << ", returnCode:" << session->getReturnCode() << "." << std::endl;
|
||||
});
|
||||
```
|
||||
8. Enable global callbacks.
|
||||
|
||||
- Session type specific Complete Callbacks, called when an async session has been completed
|
||||
|
||||
```C++
|
||||
#include <FFmpegKitConfig.h>
|
||||
|
||||
using namespace ffmpegkit;
|
||||
|
||||
FFmpegKitConfig::enableFFmpegSessionCompleteCallback([](auto session) {
|
||||
|
||||
});
|
||||
|
||||
FFmpegKitConfig::enableFFprobeSessionCompleteCallback([](auto session) {
|
||||
|
||||
});
|
||||
|
||||
FFmpegKitConfig::enableMediaInformationSessionCompleteCallback([](auto session) {
|
||||
|
||||
});
|
||||
```
|
||||
|
||||
- Log Callback, called when a session generates logs
|
||||
|
||||
```C++
|
||||
#include <FFmpegKitConfig.h>
|
||||
|
||||
using namespace ffmpegkit;
|
||||
|
||||
FFmpegKitConfig::enableLogCallback([](auto log) {
|
||||
...
|
||||
});
|
||||
```
|
||||
|
||||
- Statistics Callback, called when a session generates statistics
|
||||
|
||||
```C++
|
||||
#include <FFmpegKitConfig.h>
|
||||
|
||||
using namespace ffmpegkit;
|
||||
|
||||
FFmpegKitConfig::enableStatisticsCallback([](auto statistics) {
|
||||
...
|
||||
});
|
||||
```
|
||||
|
||||
9. Register system fonts and custom font directories.
|
||||
|
||||
```C++
|
||||
#include <FFmpegKitConfig.h>
|
||||
|
||||
using namespace ffmpegkit;
|
||||
|
||||
FFmpegKitConfig::setFontDirectoryList(std::list<std::string>{"/usr/share/fonts"}, std::map<std::string,std::string>()));
|
||||
```
|
||||
|
||||
### 4. Test Application
|
||||
|
||||
You can see how `FFmpegKit` is used inside an application by running `Linux` test applications developed under the
|
||||
[FFmpegKit Test](https://github.com/arthenica/ffmpeg-kit-test) project.
|
||||
Reference in New Issue
Block a user