simple_ffmpeg_batch_io

Reading and writing image and audio batches from/to video and audio files using an FFmpeg backend, with a simple Python API built on top of numpy.

Features

Read batches of audio and video frames from video and audio files into numpy arrays.
Write batches of frames from numpy arrays to video or audio files, even compressed
Uses static_ffmpeg to provide FFmpeg binaries in a portable way. Simple-ffmpeg-batch-io provide ffmpeg and ffprobe as commands within the virtual environment
Designed for machine learning and audio/video generation pipelines.

Installation of last version

pip install simple-ffmpeg-batch-io

Examples

Handling video files (i.e. images from video files)

Read video file at its own frame rate and frame shape

# Open it with VideoIO old way (C++ style)
inputVideo = VideoIO()
inputVideo.open(video_filename) # video file is a str or a path

# or open it a more pythonish way
inputVideo = VideoIO.reader(video_filename) # video file is a str or a path

# Here, one can read inputVideo.width, inputVideo.height, inputVideo.fps
print(inputVideo.width, inputVideo.height, inputVideo.fps)

# read one frame
frame = inputVideo.read_frame() # Here frame is a numpy arrays of shape (Width,height,channels). Channel is 3 as we support only 3 channels for the moment.

# Process video frame by frame
for frame in inputVideo.iter_frames():
    # Process frame. Here frame is a numpy arrays of shape (Width,height,channels). Channel is 3 as we support only 3 channels for the moment.
    process( frame )

# or process video using batches
n = 10
for batch in inputVideo.iter_batches(n):
    # Process batch. Here batch is a numpy arrays of shape (n,Width,height,channels). Channel is 3 as we support only 3 channels for the moment.
    process( batch )

inputVideo.close()

# Read video frame by frame with associated timestamps using with context, no need to close after end of context, close is aotomùatically called.
with VideoIO.reader(video_filename) as inputVideo:
    for frame in inputVideo.iter_frames(with_timestamps = True):
        # Here frame is encapsulated within simple-ffmpeg-batch-io.FrameContainer object
        process( frame.data )    # numpy array of shape (Width,height,channels)
        print( frame.timestamps ) # python list of the timestamp associated to the frame (video here, but same for audio), here only one element as one frame is used

# OR
# Read video batch by batch with associated timestamps using with context, no need to close after end of context, close is aotomùatically called.
n = 10
with VideoIO.reader(video_filename) as inputVideo:
    for batch in inputVideo.iter_batches(n, with_timestamps = True):
        # Here batch is encapsulated within simple-ffmpeg-batch-io.FrameContainer object
        process( batch.data )    # numpy array of shape (n,Width,height,channels)
        print( batch.timestamps ) # python list of timestamps associated to each frame (video here, but same for audio), here only one element as one frame is used

Read video file with more parameters

from simple_ffmpeg_batch_io import VideoIO

# Read video changing width, height, and fps
inputVideo = VideoIO.reader(video_file, width=100, height=100, fps=1.0)

# Read modifying only some of them
inputVideo = VideoIO.reader(video_file, width=100, fps=2.0)

Read video and write video file with dedicated ffmpeg parameters

from simple_ffmpeg_batch_io import VideoIO

# open file using filter:
# resizing to width=320, adapting height to keep aspect ratio while keep height pair (for some codec like H264)
# pixelising it to 5x5 pixels
# important note: one must not use decodingParams for scalling. Indeed, VideoIO class use filter to scale video, use width/height parameters
with VideoIO.reader("camera_4_short.mp4", width=320, height=320, decodingParams="-vf pixelize=w=5:h=5") as inputVideo,
     VideoIO.writer("camera_4_short_pix.avi", width=inputVideo.width, height=inputVideo.height, fps=inputVideo.fps ) as outputVideo:  # possible to add encodingParams to add filters, ...
    # iter over batch of 10s and write it to the output file
    batch_size = int( 10*inputVideo.fps )
    for batch in inputVideo.iter_batches(batch_size):
        outputVideo.write_batch(batch)

Handling audio from video or audio files

Read audio from audio file

# Read audio converting it to one channel, 16000 Hz, frame size of 1s as parameter is a float, start reading file at 2.0s
# default mode is plannar, i.e. samples are not interleaved, they are separated by channel after reading
# frame_size for subsequent call to read_frame, iter_frames, read_batch or iter_batches is 1.0s (16000 samples) as the value is a float, thus times in seconds.
inputAudio = AudioIO.reader(audio_filename, 16000, 1, frame_size = 1.0, start_time = 2.0 )

# If the frame_size value is an int, frame_size is considered as a number of samples, for instance to have 0.5 seconds at 16 Khz (8000 samples for each frame)
inputAudio = AudioIO.reader(audio_filename, 16000, 1, frame_size = 8000, start_time = 2.0 )


#

Static utility functions

VideoIO

from simple_ffmpeg_batch_io import VideoIO

# get (width, height, fps) of a video using a static function
print( VideoIO.get_params(video_filename) )

# get length of an audio stream as float (seconds.milliseconds)
print( VideoIO.get_time_in_sec(video_filename) )

AudioIO

from simple_ffmpeg_batch_io import AudioIO

# get (channels,sample_rate) of a stream using astatic function
print( AudioIO.get_params(filename) )

# get length of video stream as float (seconds.milliseconds)
print( AudioIO.get_time_in_sec(filename) )

Submodules

View Source

 1# Author: Dominique Vaufreydaz
 2
 3"""
 4.. include:: ../../README.md
 5 :start-after: # simple-ffmpeg-batch-io
 6
 7# Submodules
 8"""
 9
10# __init__.py
11from .VideoIO import VideoIO
12from .AudioIO import AudioIO
13from .FrameCounter import FrameCounter
14
15__all__ = [
16    "VideoIO",
17    "AudioIO",
18    "FrameCounter",
19    "FrameContainer",
20]

class VideoIO.VideoIOException(builtins.Exception): View Source

35    class VideoIOException(Exception):
36        """
37        Dedicated exception class for VideoIO class.
38        """
39        def __init__(self, message="Error while reading/writing video occurs"):
40            self.message = message
41            super().__init__(self.message)

Dedicated exception class for VideoIO class.

VideoIO.VideoIOException(message='Error while reading/writing video occurs') View Source

39        def __init__(self, message="Error while reading/writing video occurs"):
40            self.message = message
41            super().__init__(self.message)

message

class VideoIO.PixelFormat(enum.Enum): View Source

43    class PixelFormat(Enum):
44        """
45        Enum class for supported input video type: GBR 24 bits or RGB 24 bis.
46        """
47        GBR24 = 'bgr24' # default format
48        RGB24 = 'rgb24'

Enum class for supported input video type: GBR 24 bits or RGB 24 bis.

GBR24 = <PixelFormat.GBR24: 'bgr24'>

RGB24 = <PixelFormat.RGB24: 'rgb24'>

class AudioIO.AudioIOException(builtins.Exception): View Source

35    class AudioIOException(Exception):
36        """
37        Dedicated exception class for AudioIO class.
38        """
39        def __init__(self, message="Error while reading/writing video occurs"):
40            self.message = message
41            super().__init__(self.message)

Dedicated exception class for AudioIO class.

AudioIO.AudioIOException(message='Error while reading/writing video occurs') View Source

39        def __init__(self, message="Error while reading/writing video occurs"):
40            self.message = message
41            super().__init__(self.message)

message

class AudioIO.AudioFormat(enum.Enum): View Source

43    class AudioFormat(Enum):
44        """
45        Enum class for supported input video type: 32-bit float is the only supported type for the moment.
46        """
47        PCM32LE = 'pcm_f32le' # default format (unique mode for the moment)

Enum class for supported input video type: 32-bit float is the only supported type for the moment.

PCM32LE = <AudioFormat.PCM32LE: 'pcm_f32le'>

class FrameCounter: View Source

 16class FrameCounter:
 17    """
 18    Create a ``FrameCounter`` to follow elapsed time in audio/video file in read or write mode. Static utility functions allow to format elapsed time.
 19    """
 20
 21    class FrameCounterException(Exception):
 22        """
 23        Dedicated exception class for FrameCounter class.
 24        """
 25        def __init__(self, message="Error while setting FrameCounter parameters."):
 26            self.message = message
 27            super().__init__(self.message)
 28
 29    _fps: float # (private)
 30    """ Fps of current stream """
 31
 32    _frame_count: int # (private)
 33    """ Frame count in the current stream """
 34
 35    def __init__(self, fps: Union[int, float]):
 36        """
 37        Create a VideoIO object giving ffmpeg/ffrobe loglevel and defining debug mode
 38
 39        Parameters
 40        ----------
 41        fps: int or float.
 42            Frames per second of the associated stream.
 43        """
 44        # check init fps value
 45        self._fps = float(fps)
 46        if self._fps <= 0.0:
 47            raise FrameCounterException("fps must be > 0.0.")
 48
 49        # 2 modes
 50        self._frame_count = 0       # at 00:00:00.000
 51
 52    # support +=
 53    def __iadd__(self, other: Union[int, float]):
 54        """
 55        Support += operator for FrameCounter. 
 56
 57        Parameters
 58        ----------
 59        other: int or float.
 60            If other is a float, add the number of frame to add 'other' seconds (thus other * self._fps samples).
 61            If other is an int, add the value as a number of samples in the stream.
 62        """        
 63        if isinstance(other,float):
 64            # float means adding time
 65            self._frame_count += int(other * self._fps) # number of second * Nb of elements per seconds
 66        else:
 67            # for int, add number of element
 68            self._frame_count += other
 69        return self
 70    
 71    @property
 72    def frame_count(self):
 73        """
 74        Property to get underlying self._frame_count. Idea is to control setter to valid setting values.
 75        """   
 76        return self._frame_count
 77
 78    @frame_count.setter
 79    def frame_count(self, value: int):
 80        """
 81        Setter for underlying self._frame_count controlling setting value.
 82        """   
 83        if value < 0:
 84            raise FrameCounterException("frame_count must be >= 0")
 85        self._frame_count = value
 86
 87    @property
 88    def fps(self):
 89        """
 90        Property to get underlying self._fps.
 91        """
 92        return self._fps
 93
 94    @staticmethod
 95    def format_time(nb_frames: int, fps: float, show_ms : bool = True, show_days : bool = False) -> str:
 96        """
 97        Static function to format time given by a number of frames and an fps. show_ms value defines if we show milliseconds,
 98        show_days to show days instead of cummulative hour count.
 99
100        Parameters
101        ----------
102        nb_frames: int.
103            Number of samples already present in the stream.
104            
105        fps: float.
106            Fps of the associated stream.
107            
108        show_ms: bool.
109            Flag to say if we want to show milliseconds in the output str.
110            
111        show_days: bool.
112            Flag to say if we want to show says instead of cumulative hours in the output str.
113
114        Returns
115        -------
116            str representing corresponding time. Either 26:15:00 (show_ms=False, show_days=False), 26:15:00.500 (show_ms=True, show_days=False)
117            or 1 day(s) 02:15:00.500 (show_ms=True, show_days=True)
118        """  
119        # exact time in seconds (float)
120        exact_seconds = nb_frames / fps
121
122        # integer part for days/hours/minutes/seconds
123        total_seconds = int(exact_seconds)
124
125        # milliseconds = decimal part * 1000
126        millis = int(round((exact_seconds - total_seconds) * 1000))
127
128        # handle the case where rounding results in 1000 ms
129        if millis == 1000:
130            millis = 0
131            total_seconds += 1
132
133        if show_days:
134            # compute number of days, hours, minutes, seconds
135            days, mod = divmod(total_seconds, 24 * 3600)
136            hours, mod = divmod(mod, 3600)
137            minutes, seconds = divmod(mod, 60)
138
139            if days > 0:
140                days = f"{days} days(s) "
141            else:
142                days = ""
143        else:
144            days = "" # no day as show_days = False
145            hours, mod = divmod(total_seconds, 3600)
146            minutes, seconds = divmod(mod, 60)
147
148        if show_ms == True:
149            millis = f".{millis:03d}"
150        else:
151            millis = ""
152
153        return f"{days}{hours:02d}:{minutes:02d}:{seconds:02d}{millis}"
154
155    def get_elapsed_time_as_str(self) -> str:
156        """
157        Get elapsed time as string representing a float value rounded to 3 decimals.
158
159        Returns
160        -------
161            str representing corresponding time in float format rounded to 3 decimals.
162        """
163        return f"{float(self._frame_count)/self._fps:.3f}"
164
165    def get_formated_elapsed_time_as_str(self, show_ms : bool = True, show_days : bool = False) -> str:
166        """
167        Get elapsed time as string representing time with different mode (see ``FrameCounter.format_time`` for parameter explanation).
168        Returns
169        -------
170            str representing corresponding time in float format rounded to 3 decimals.
171        """
172        # frame count to time correction is done in format_time
173        return FrameCounter.format_time(self._frame_count, self._fps, show_ms, show_days)
174
175    def get_elapsed_time(self) -> float:
176        """
177        Get elapsed time as float value rounded to 3 decimals.
178
179        Returns
180        -------
181            str representing corresponding time in float format rounded to 3 decimals.
182        """
183        return round(float(self._frame_count)/self._fps,3)

Create a FrameCounter to follow elapsed time in audio/video file in read or write mode. Static utility functions allow to format elapsed time.

FrameCounter(fps: int | float) View Source

35    def __init__(self, fps: Union[int, float]):
36        """
37        Create a VideoIO object giving ffmpeg/ffrobe loglevel and defining debug mode
38
39        Parameters
40        ----------
41        fps: int or float.
42            Frames per second of the associated stream.
43        """
44        # check init fps value
45        self._fps = float(fps)
46        if self._fps <= 0.0:
47            raise FrameCounterException("fps must be > 0.0.")
48
49        # 2 modes
50        self._frame_count = 0       # at 00:00:00.000

Create a VideoIO object giving ffmpeg/ffrobe loglevel and defining debug mode

Parameters

fps: int or float. Frames per second of the associated stream.

frame_count View Source

71    @property
72    def frame_count(self):
73        """
74        Property to get underlying self._frame_count. Idea is to control setter to valid setting values.
75        """   
76        return self._frame_count

Property to get underlying self._frame_count. Idea is to control setter to valid setting values.

fps View Source

87    @property
88    def fps(self):
89        """
90        Property to get underlying self._fps.
91        """
92        return self._fps

Property to get underlying self._fps.

@staticmethod

def format_time( nb_frames: int, fps: float, show_ms: bool = True, show_days: bool = False) -> str: View Source

 94    @staticmethod
 95    def format_time(nb_frames: int, fps: float, show_ms : bool = True, show_days : bool = False) -> str:
 96        """
 97        Static function to format time given by a number of frames and an fps. show_ms value defines if we show milliseconds,
 98        show_days to show days instead of cummulative hour count.
 99
100        Parameters
101        ----------
102        nb_frames: int.
103            Number of samples already present in the stream.
104            
105        fps: float.
106            Fps of the associated stream.
107            
108        show_ms: bool.
109            Flag to say if we want to show milliseconds in the output str.
110            
111        show_days: bool.
112            Flag to say if we want to show says instead of cumulative hours in the output str.
113
114        Returns
115        -------
116            str representing corresponding time. Either 26:15:00 (show_ms=False, show_days=False), 26:15:00.500 (show_ms=True, show_days=False)
117            or 1 day(s) 02:15:00.500 (show_ms=True, show_days=True)
118        """  
119        # exact time in seconds (float)
120        exact_seconds = nb_frames / fps
121
122        # integer part for days/hours/minutes/seconds
123        total_seconds = int(exact_seconds)
124
125        # milliseconds = decimal part * 1000
126        millis = int(round((exact_seconds - total_seconds) * 1000))
127
128        # handle the case where rounding results in 1000 ms
129        if millis == 1000:
130            millis = 0
131            total_seconds += 1
132
133        if show_days:
134            # compute number of days, hours, minutes, seconds
135            days, mod = divmod(total_seconds, 24 * 3600)
136            hours, mod = divmod(mod, 3600)
137            minutes, seconds = divmod(mod, 60)
138
139            if days > 0:
140                days = f"{days} days(s) "
141            else:
142                days = ""
143        else:
144            days = "" # no day as show_days = False
145            hours, mod = divmod(total_seconds, 3600)
146            minutes, seconds = divmod(mod, 60)
147
148        if show_ms == True:
149            millis = f".{millis:03d}"
150        else:
151            millis = ""
152
153        return f"{days}{hours:02d}:{minutes:02d}:{seconds:02d}{millis}"

Static function to format time given by a number of frames and an fps. show_ms value defines if we show milliseconds, show_days to show days instead of cummulative hour count.

Parameters

nb_frames: int. Number of samples already present in the stream.

fps: float. Fps of the associated stream.

show_ms: bool. Flag to say if we want to show milliseconds in the output str.

show_days: bool. Flag to say if we want to show says instead of cumulative hours in the output str.

Returns

str representing corresponding time. Either 26:15:00 (show_ms=False, show_days=False), 26:15:00.500 (show_ms=True, show_days=False)
or 1 day(s) 02:15:00.500 (show_ms=True, show_days=True)

def get_elapsed_time_as_str(self) -> str: View Source

155    def get_elapsed_time_as_str(self) -> str:
156        """
157        Get elapsed time as string representing a float value rounded to 3 decimals.
158
159        Returns
160        -------
161            str representing corresponding time in float format rounded to 3 decimals.
162        """
163        return f"{float(self._frame_count)/self._fps:.3f}"

Get elapsed time as string representing a float value rounded to 3 decimals.

Returns

str representing corresponding time in float format rounded to 3 decimals.

def get_formated_elapsed_time_as_str(self, show_ms: bool = True, show_days: bool = False) -> str: View Source

165    def get_formated_elapsed_time_as_str(self, show_ms : bool = True, show_days : bool = False) -> str:
166        """
167        Get elapsed time as string representing time with different mode (see ``FrameCounter.format_time`` for parameter explanation).
168        Returns
169        -------
170            str representing corresponding time in float format rounded to 3 decimals.
171        """
172        # frame count to time correction is done in format_time
173        return FrameCounter.format_time(self._frame_count, self._fps, show_ms, show_days)

Get elapsed time as string representing time with different mode (see FrameCounter.format_time for parameter explanation).

Returns

str representing corresponding time in float format rounded to 3 decimals.

def get_elapsed_time(self) -> float: View Source

175    def get_elapsed_time(self) -> float:
176        """
177        Get elapsed time as float value rounded to 3 decimals.
178
179        Returns
180        -------
181            str representing corresponding time in float format rounded to 3 decimals.
182        """
183        return round(float(self._frame_count)/self._fps,3)

Get elapsed time as float value rounded to 3 decimals.

Returns

str representing corresponding time in float format rounded to 3 decimals.

class FrameCounter.FrameCounterException(builtins.Exception): View Source

21    class FrameCounterException(Exception):
22        """
23        Dedicated exception class for FrameCounter class.
24        """
25        def __init__(self, message="Error while setting FrameCounter parameters."):
26            self.message = message
27            super().__init__(self.message)

Dedicated exception class for FrameCounter class.

FrameCounter.FrameCounterException(message='Error while setting FrameCounter parameters.') View Source

25        def __init__(self, message="Error while setting FrameCounter parameters."):
26            self.message = message
27            super().__init__(self.message)

message