From 8ff7dcd1bb0e3cbee67c13a3429df94a4c165108 Mon Sep 17 00:00:00 2001 From: Clement Champetier Date: Fri, 20 May 2016 14:55:07 +0200 Subject: [PATCH 1/7] README: move Tests section to INSTALL file --- INSTALL.md | 20 ++++++++++++++++++++ README.md | 17 ----------------- 2 files changed, 20 insertions(+), 17 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 855fe534..738e219d 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -73,3 +73,23 @@ brew install avtranscoder --devel brew deps avtranscoder brew install avtranscoder --only-dependencies ``` + +#### Tests + +###### nosetests +Python tests using nosetests. +``` +cd test/pyTest +nosetests +``` + +Some tests need environment variables to be executed (otherwise they will be skipped): +* ```AVTRANSCODER_TEST_VIDEO_AVI_FILE``` +* ```AVTRANSCODER_TEST_VIDEO_MP4_FILE``` +* ```AVTRANSCODER_TEST_VIDEO_MOV_FILE``` +* ```AVTRANSCODER_TEST_AUDIO_WAVE_FILE``` +* ```AVTRANSCODER_TEST_AUDIO_MOV_FILE``` +* ```AVTRANSCODER_TEST_IMAGE_PNG_FILE``` +* ```AVTRANSCODER_TEST_IMAGE_JPG_FILE``` + +Note: for continuous integration, we launch tests with media files contained in [avTranscoder-data](https://github.com/avTranscoder/avTranscoder-data) repository. diff --git a/README.md b/README.md index 9f364fdd..0472ea3d 100644 --- a/README.md +++ b/README.md @@ -33,23 +33,6 @@ See [**Doxygen documentation**](http://avtranscoder.github.io/avTranscoder-doxyg #### Compilation See [**INSTALL.md**](INSTALL.md) -#### Tests - -###### nosetests -Python tests using nosetests. -``` -cd test/pyTest -nosetests -``` - -Some tests need environment variables to be executed (otherwise they will be skipped): -* ```AVTRANSCODER_TEST_VIDEO_FILE``` -* ```AVTRANSCODER_TEST_AUDIO_WAVE_FILE``` -* ```AVTRANSCODER_TEST_AUDIO_MOV_FILE``` - -Note: for continuous integration, we launch tests with media files contained in ```avTranscoder-data``` repository. - - #### Packaging ###### Build openSUSE From 8cf6d7398aba49440af00064e55f8c127e27c725 Mon Sep 17 00:00:00 2001 From: Clement Champetier Date: Fri, 20 May 2016 14:57:53 +0200 Subject: [PATCH 2/7] INSTALL: updated commands to build the project Try to give the easiest commands. --- INSTALL.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 738e219d..41447e91 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -9,31 +9,30 @@ AvTranscoder can depend on ffmpeg, libav, or any fork of these projects that fol #### To build ``` -mkdir build && cd build -cmake .. +cmake . make make install ``` #### To indicate a specific ffmpeg/libav folder ``` -cmake .. -DCMAKE_PREFIX_PATH=/path/to/your/install +cmake . -DCMAKE_PREFIX_PATH=/path/to/your/install ``` #### To not build apps ``` -cmake .. -DAVTRANSCODER_DISABLE_APPS=True +cmake . -DAVTRANSCODER_DISABLE_APPS=True ``` #### To not build bindings ``` -cmake .. -DAVTRANSCODER_DISABLE_BINDINGS=True +cmake . -DAVTRANSCODER_DISABLE_BINDINGS=True ``` ``` -cmake .. -DAVTRANSCODER_DISABLE_PYTHON_BINDING=True +cmake . -DAVTRANSCODER_DISABLE_PYTHON_BINDING=True ``` ``` -cmake .. -DAVTRANSCODER_DISABLE_JAVA_BINDING=True +cmake . -DAVTRANSCODER_DISABLE_JAVA_BINDING=True ``` #### Other useful flags @@ -50,7 +49,7 @@ cmake .. -DCMAKE_BUILD_TYPE=Release/Debug cmake .. -DAVTRANSCODER_PYTHON_VERSION_OF_BINDING=2.7 ``` -#### Mac OSX using homebrew +#### To install on Mac OSX ###### Install homebrew http://brew.sh/ From 4dec4efdf90d750a969347d08d31036bd2da1df8 Mon Sep 17 00:00:00 2001 From: Clement Champetier Date: Fri, 20 May 2016 15:13:43 +0200 Subject: [PATCH 3/7] README: updated project baseline --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0472ea3d..94844538 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # avTranscoder -C++ API for FFmpeg / Libav +High level API for FFmpeg / Libav. Based on FFmpeg/Libav libraries to support various video and audio formats, avTranscoder provides the high level API to re-wrap or transcode media easily. From 7901f760c4a71488977732d4b76cf95a33d23b35 Mon Sep 17 00:00:00 2001 From: Clement Champetier Date: Fri, 20 May 2016 15:14:04 +0200 Subject: [PATCH 4/7] README: updated "What you need to know" section --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 94844538..f31fd5b8 100644 --- a/README.md +++ b/README.md @@ -15,11 +15,11 @@ Click on the badge above to have a big picture view of what's in progress and ho :warning: The latest avTranscoder API does not fit with libav. -#### What you need to know -* C++ library -* Java and Python bindings generated with SWIG -* multiplateform (Linux, MAC, Windows) -* your call to be based on Libav, FFmpeg, or your custom fork of one of these librairies +#### The basics +* avTranscoder is a C++ library. +* avTranscoder uses [SWIG](http://www.swig.org/) to generate __Java__ and __Python__ bindings. +* avTranscoder is multiplateform (Linux, MAC, Windows). +* avTranscoder could be based on [Libav](https://libav.org/), [FFmpeg](https://ffmpeg.org/), or your custom fork of one of these librairies. #### License See [**COPYING.md**](COPYING.md) From 99188e24e3c85d3ca22c4b26596a6af7749cd339 Mon Sep 17 00:00:00 2001 From: Clement Champetier Date: Fri, 20 May 2016 15:14:49 +0200 Subject: [PATCH 5/7] INSTALL: added link to CMake build system --- INSTALL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/INSTALL.md b/INSTALL.md index 41447e91..0b719e17 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,6 +1,6 @@ # Compilation -AvTranscoder uses CMake as build system. +AvTranscoder uses [CMake](http://www.cmake.org/) as build system. #### Dependencies AvTranscoder can depend on ffmpeg, libav, or any fork of these projects that follow the same API. From 31205c318a1dd1b74b32fb0baec4220456cf0cd7 Mon Sep 17 00:00:00 2001 From: Clement Champetier Date: Fri, 20 May 2016 17:56:24 +0200 Subject: [PATCH 6/7] USAGE: added "API" and "Projects which uses avTranscoder" sections --- USAGE.md | 176 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 154 insertions(+), 22 deletions(-) diff --git a/USAGE.md b/USAGE.md index 050c5a5c..25d75522 100644 --- a/USAGE.md +++ b/USAGE.md @@ -1,39 +1,124 @@ # How to use avTranscoder -Check out applications contained in the project to see examples of how to use the library in C++, Java or Python. +## When to use avTranscoder +* when you need to access the API of ffmpeg, but you want to avoid the head-hurting part of AVPacket, AV_TIME_BASE and all the stuff deep inside ffmpeg. +* when you would like to access the ffmpeg features in your language (currently Java and python, tomorrow what you want!). -#### In C++ -Set environment: -``` -export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/ffmpeg/lib:/path/to/avtranscoder/lib -export PATH=$PATH:/path/to/avtranscoder/bin -``` -#### In Java -Add argument to the JVM: -``` --Djava.library.path=/path/to/avtranscoder/lib/java +## API +The original code is in C++, but almost all the methods are translated into python/java without any changes. +So a good way to start is to have a look at the [C++ code](src/AvTranscoder) (since the generated python/java code is ugly). + +In the sake of brevity, the example code of the following section is written in python. + +#### At the beginning +Before starting anything, you need to register all the codecs, formats, filters which are enabled at configuration time. +So your first avTranscoder instruction should be: +```python +avtranscoder.preloadCodecsAndFormats() ``` -Set environment: + +#### Analyse media +To analyse a media, you can create an [__InputFile__](src/AvTranscoder/file/InputFile.hpp) and have access to all header [__properties__](src/AvTranscoder/properties). +```python +# create InputFile +inputFile = avtranscoder.InputFile("/path/to/media/file.mov") + +# get access to properties +properties = inputFile.getProperties() + +# print all format properties +for prop, value in properties.asVector(): + print(prop + ": " + str(value)) + +# print all properties of each stream +for stream in properties.getStreamProperties(): + print("------ Properties of stream at index " + str(stream.getStreamIndex()) + " -----") + for prop, value in stream.asVector(): + print(prop + ": " + str(value)) + +# write all media properties as JSON in a file +import json +with open('data.txt', 'w') as outfile: + json.dump(properties.allPropertiesAsJson(), outfile) ``` -export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/ffmpeg/lib + +Some properties could have a value of _null_ because: +* the property is not indicated in the media. +* the property is not accessible in the header. + +For the second point, you can launch a deeper analysis. +This is the case if you would like to have access to the GOP structure of a video stream: +```python +# create InputFile +inputFile = avtranscoder.InputFile("/path/to/media/file.mov") + +# analyse first GOP (show progression in console) +progress = avtranscoder.NoDisplayProgress() +inputFile.analyse(progress, avtranscoder.eAnalyseLevelFirstGop) + +# get access to properties +properties = inputFile.getProperties() +videoProperties = properties.getVideoProperties()[0] +print videoProperties.getGopSize() +print videoProperties.getGopStructure() ``` -#### In Python -Set environment: +Check out [__avmeta__](app/avMeta/avMeta.cpp) application to see a C++ example of this use case. + +#### Process media +An important part of the API concerns media processing. The general overview of the workflow could be separate in 2 main cases: +* _transcoding_: demuxing, decoding, transform, encoding and muxing. Here we can update all parts of the media, from the container to the codec used to encode data. +See the [transcoding process](https://ffmpeg.org/ffmpeg.html#toc-Detailed-description) in ffmpeg documentation. +* _rewrap_: omit the decoding, transform and encoding steps. It is useful for changing the container format or modifying container-level metadata. +See the [copy](https://ffmpeg.org/ffmpeg.html#Stream-copy) paramer in ffmpeg documentation. + +The main class to process media is the [__Transcoder__](src/AvTranscoder/transcoder/Transcoder.hpp). + +Here a rewrapping example to update container (from AVI to MOV): +```python +ouputFile = avtranscoder.OutputFile("/path/to/output/media.mov") +transcoder = avtranscoder.Transcoder(ouputFile) +transcoder.add("/path/to/input/media.avi") +transcoder.process() +``` +Check out [__pyrewrap__](app/pyRewrap/pyrewrap.py) application to see a python example of this use case. + +Here a transcoding example to encode video and audio streams: +```python +ouputFile = avtranscoder.OutputFile("/path/to/output/media.mov") +transcoder = avtranscoder.Transcoder(ouputFile) + +# transcode a video stream at index 0 to H264 High Quality +transcoder.add("/path/to/input/media.avi", 0, "h264-hq") +# transcode an audio stream at index 1 to PCM 24bits 48kHz mono +transcoder.add("/path/to/input/media.wav", 1, "wave24b48kmono") + +# show the progression in console +progress = avtranscoder.ConsoleProgress() +transcoder.process(progress) ``` -export PYTHONPATH=$PYTHONPATH:/path/to/avtranscoder/lib/python/site-packages/ -export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/ffmpeg/lib +Check out [__avprocessor__](app/avProcessor/avProcessor.cpp) application to see a C++ example of this use case. + +An other important parameter is the transcoding policy, which defines how we manage the process in case of several streams. By default the process ends at the end of the longest stream (so the shorter streams are filled with silence or black images). +To change the transcoding policy: +```python +# stop the process when the output stream at index 0 is finished +transcoder.setProcessMethod(avtranscoder.eProcessMethodBasedOnStream, 0) + +# stop the process when the output file has a duration of 50s +transcoder.setProcessMethod(avtranscoder.eProcessMethodBasedOnDuration, 0, 50) ``` -#### Use profiles +#### More on process: use profiles To wrap/unwrap/encode/decode, avTranscoder manipulates profiles. A profile is a set of key-value given as parameters to the InputFile(unwrap), the OutputFile(wrap), the Video/AudioDecoder(decode) or the Video/AudioEncoder(encode). There are two ways to manipulate profiles: * create profiles inside your code, by instanciate ```Map``` structures. -* create profiles outside your code, by create text files. +* create profiles outside your code, by create text files. You have examples [here](avprofiles). + To indicate the path to the text files, export environment variable: -``` +```bash export AVPROFILES=/path/to/profiles ``` @@ -44,7 +129,6 @@ avProfileLongName=profileLongName avProfileType=avProfileTypeFormat format=formatName ``` - The minimum video profile (encode/decode) is: ``` avProfileName=profileName @@ -52,7 +136,6 @@ avProfileLongName=profileLongName avProfileType=avProfileTypeVideo codec=codecName ``` - The minimum audio profile (encode/decode) is: ``` avProfileName=profileName @@ -60,3 +143,52 @@ avProfileLongName=profileLongName avProfileType=avProfileTypeAudio codec=codecName ``` + +To encode a video stream using your custom profile: +```python +ouputFile = avtranscoder.OutputFile("/path/to/output/media.mov") +transcoder = avtranscoder.Transcoder(ouputFile) +transcoder.add("/path/to/input/media.avi", 0, "profileName") +transcoder.process() +``` + +To go into more details about the avTranscoder API, take a look at the [__Doxygen documentation__](http://avtranscoder.github.io/avTranscoder-doxygen/). + +## Environment +#### In C++ +Set environment: +```bash +export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/ffmpeg/lib:/path/to/avtranscoder/lib +export PATH=$PATH:/path/to/avtranscoder/bin +``` + +#### In Java +Add argument to the JVM: +```bash +-Djava.library.path=/path/to/avtranscoder/lib/java +``` +Set environment: +```bash +export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/ffmpeg/lib +``` + +#### In Python +Set environment: +```bash +export PYTHONPATH=$PYTHONPATH:/path/to/avtranscoder/lib/python/site-packages/ +export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/ffmpeg/lib +``` + +## Projects which uses avTranscoder +#### TuttleOFX +TuttleOFX is a library to connect and batch operations with OpenFx plugins. It comes with a set of plugins that allows you to batch process on movies and file sequences. +TuttOFX uses avTranscoder for the [AudioVideo plugin](https://github.com/tuttleofx/TuttleOFX/tree/develop/plugins/image/io/AudioVideo), one of its io plugins. + +#### PADdef / Slingshot +PADdef is a platform developed by [Mikros Image](http://www.mikrosimage.eu/) for France Télévisions's new digital distribution centers. Its purpose is to handle the delivery of ready-to-broadcast feature material. +Slingshot is its mirror project for Belgium broadcasters: Medialaan, RTBF and RTL. +PADdef / Slingshot uses avTranscoder in one of its application to transcode media in post-production labs. + +#### Ploud +A set of applications developed by [Mikros Image](http://www.mikrosimage.eu/) to analyse, visualize and correct the loudness. +PADdef / Slingshot uses avTranscoder in [one of its application](https://github.com/mikrosimage/loudness_validator/tree/develop/app/mediaAnalyser) to give decoded data to the loudness analyser. From 825bf2b78cac77003669a70df3185e1afc4f895a Mon Sep 17 00:00:00 2001 From: Clement Champetier Date: Wed, 25 May 2016 18:13:05 +0200 Subject: [PATCH 7/7] USAGE: improved english spelling --- USAGE.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/USAGE.md b/USAGE.md index 25d75522..0cad763d 100644 --- a/USAGE.md +++ b/USAGE.md @@ -1,13 +1,13 @@ # How to use avTranscoder ## When to use avTranscoder -* when you need to access the API of ffmpeg, but you want to avoid the head-hurting part of AVPacket, AV_TIME_BASE and all the stuff deep inside ffmpeg. -* when you would like to access the ffmpeg features in your language (currently Java and python, tomorrow what you want!). +* when you need to access the API of ffmpeg, but you want to avoid the head-hurting part of AVPacket, AV_TIME_BASE and all the deep ffmpeg components. +* when you would like to access the ffmpeg features in your language (currently Java and Python, tomorrow what you want!). ## API -The original code is in C++, but almost all the methods are translated into python/java without any changes. -So a good way to start is to have a look at the [C++ code](src/AvTranscoder) (since the generated python/java code is ugly). +The original code is in C++, but almost all the methods are translated into Java/Python without any changes. +So you should start having a look at the [C++ code](src/AvTranscoder) (since the generated Java/Python code is ugly). In the sake of brevity, the example code of the following section is written in python. @@ -48,7 +48,7 @@ Some properties could have a value of _null_ because: * the property is not accessible in the header. For the second point, you can launch a deeper analysis. -This is the case if you would like to have access to the GOP structure of a video stream: +For instance, you might like to access to the GOP structure: ```python # create InputFile inputFile = avtranscoder.InputFile("/path/to/media/file.mov") @@ -67,7 +67,7 @@ print videoProperties.getGopStructure() Check out [__avmeta__](app/avMeta/avMeta.cpp) application to see a C++ example of this use case. #### Process media -An important part of the API concerns media processing. The general overview of the workflow could be separate in 2 main cases: +An important part of the API concerns media processing. The general overview of the workflow could be separated into two main cases: * _transcoding_: demuxing, decoding, transform, encoding and muxing. Here we can update all parts of the media, from the container to the codec used to encode data. See the [transcoding process](https://ffmpeg.org/ffmpeg.html#toc-Detailed-description) in ffmpeg documentation. * _rewrap_: omit the decoding, transform and encoding steps. It is useful for changing the container format or modifying container-level metadata. @@ -191,4 +191,4 @@ PADdef / Slingshot uses avTranscoder in one of its application to transcode medi #### Ploud A set of applications developed by [Mikros Image](http://www.mikrosimage.eu/) to analyse, visualize and correct the loudness. -PADdef / Slingshot uses avTranscoder in [one of its application](https://github.com/mikrosimage/loudness_validator/tree/develop/app/mediaAnalyser) to give decoded data to the loudness analyser. +Ploud uses avTranscoder in [one of its application](https://github.com/mikrosimage/loudness_validator/tree/develop/app/mediaAnalyser) to give decoded data to the loudness analyser.