simple-ffmpeg-batch-io 1.0.0__py3-none-any.whl

simple_ffmpeg_batch_io/AudioIO.py

@@ -0,0 +1,824 @@
+"""
+Read/write audio frames or batches of audio frames from (compressed) file, including video file with audio stream(s), using FFmpeg backend.
+
+This module defines the main `AudioIO` class used to open audio streams,
+read audio frames or batches of frames, and write processed outputs.
+
+Authors
+-------
+Dominique Vaufreydaz (inspired from original C++ code: https://github.com/Vaufreyd/ReadWriteVideosWithOpenCV)
+
+"""
+
+__authors__ = ("Dominique Vaufreydaz")
+
+import sys
+import subprocess as sp
+import re
+from enum import Enum
+from typing import Union
+
+import numpy as np
+
+from .FrameCounter import FrameCounter
+from .FrameContainer import FrameContainer
+from .PipeMode import PipeMode
+
+# init static_ffmpeg at import time, first time it will download ffmpeg executables
+import static_ffmpeg
+static_ffmpeg.add_paths()
+
+class AudioIO:
+    # "static" variables  to ffmpeg, ffprobe executables
+    audioProgram, paramProgram = static_ffmpeg.run.get_or_fetch_platform_executables_else_raise()
+
+    class AudioIOException(Exception):
+        """
+        Dedicated exception class for AudioIO class.
+        """
+        def __init__(self, message="Error while reading/writing video occurs"):
+            self.message = message
+            super().__init__(self.message)
+
+    class AudioFormat(Enum):
+        """
+        Enum class for supported input video type: 32-bit float is the only supported type for the moment.
+        """
+        PCM32LE = 'pcm_f32le' # default format (unique mode for the moment)
+
+    @classmethod
+    def reader(cls, filename, **kwargs):
+        """
+        Create and open an AudioIO object in reader mode
+
+        See ``AudioIO.open`` for the full list of accepted parameters.
+        """
+        reader = cls()
+        reader.open(filename, **kwargs)
+        return reader
+
+    @classmethod
+    def writer(cls, filename, **kwargs):
+        """
+        Create and open an AudioIO object in writer mode
+
+        See ``AudioIO.create`` for the full list of accepted parameters.
+        """
+        writer = cls()
+        writer.create(filename, **kwargs)
+        return writer
+
+    # To use with context manager "with AudioIO.reader(...) as f:' for instance
+    def __enter__(self):
+        """
+        Method call at initialisation of a context manager like "with AudioIO.reader/writer(...) as f:' for instance
+        """
+        # simply return myself
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """
+        Method call when existing of a context manager like "with AudioIO.reader/writer(...) as f:' for instance
+        """
+        # close AudioIO
+        self.close()
+        return False
+
+    @staticmethod
+    def get_time_in_sec(filename, *, debug=False, logLevel=16):
+        """
+        Static method to get length of an audio file (or video file containing audio) in seconds including milliseconds as decimal part (3 decimals).
+
+        Parameters
+        ----------
+        filename : str or path. 
+            Raw audio waveform as a 1D array.
+
+        debug : bool (default False).
+            Show debug info.
+
+        log_level: int (default 16).
+            Log level to pass to the underlying ffmpeg/ffprobe command.
+        
+        Returns
+        ----------
+        float
+            Length in seconds of video file (including milliseconds as decimal part with 3 decimals)
+        """
+        
+        cmd = [AudioIO.paramProgram, # ffprobe
+                    '-hide_banner',
+                    '-loglevel', str(logLevel),
+                    '-show_entries', 'format=duration',
+                    '-of', 'default=noprint_wrappers=1:nokey=1',
+                    filename
+                    ]
+
+        if debug == True:
+            print(' '.join(cmd))
+
+        # call ffprobe and get params in one single line
+        lpipe = sp.Popen(cmd, stdout=sp.PIPE)
+        output = lpipe.stdout.readlines()
+        lpipe.terminate()
+        # transform Bytes output to one single string
+        output = ''.join( [element.decode('utf-8') for element in output])
+
+        try:
+            return float(output)
+        except (ValueError, TypeError):
+            return None
+
+    @staticmethod
+    def get_params(filename, *, debug=False, logLevel=16):
+        """
+        Static method to get params (channels,sample_rate) of a (video containing) audio file in seconds.
+
+        Parameters
+        ----------
+        filename : str or path.
+            Raw audio waveform as a 1D array.
+
+        debug : bool (default (False).
+            Show debug info.
+
+        log_level: int (default 16).
+            Log level to pass to the underlying ffmpeg/ffprobe command.
+
+        Returns
+        ----------
+        tuple
+            Tuple containing (channels,sample_rate) of the file
+        """
+        cmd = [AudioIO.paramProgram, # ffprobe
+                    '-hide_banner',
+                    '-loglevel', str(logLevel),
+                    '-show_entries', 'stream=channels,sample_rate',
+                    filename
+                    ]
+
+        if debug == True:
+            print(' '.join(cmd))
+
+        # call ffprobe and get params in one single line
+        lpipe = sp.Popen(cmd, stdout=sp.PIPE)
+        output = lpipe.stdout.readlines()
+        lpipe.terminate()
+        # transform Bytes output to one single string
+        output = ''.join( [element.decode('utf-8') for element in output])
+
+        pattern_sample_rate = r'sample_rate=(\d+)'
+        pattern_channels = r'channels=(\d+)'
+
+        # Search for values in the ffprobe output
+        match_sample_rate = re.search(pattern_sample_rate, output, flags=re.MULTILINE)
+        match_channels = re.search(pattern_channels, output, flags=re.MULTILINE)
+
+        # Extraction des valeurs
+        if match_sample_rate:
+            sample_rate = int(match_sample_rate.group(1))
+        else:
+            raise AudioIO.AudioIOException("Unable to get audio sample_rate of '" + str(filename) + "'")
+
+        if match_channels:
+            channels = int(match_channels.group(1))
+        else:
+            raise AudioIO.AudioIOException("Unable to get audio channels of '" + str(filename) + "'")
+
+        return (channels,sample_rate)
+
+        # Attributes
+        mode: PipeMode
+        """ Pipemode of the current object (default PipeMode.UNK_MODE)"""
+
+        loglevel: int
+        """ loglevel of the underlying ffmpeg backend for this object (default 16)"""
+
+        debugModel: bool
+        """ debutMode flag for this object (print debut info, default False)"""
+
+        channels: int
+        """ Number of channels of images (default -1) """
+
+        sample_rate: int
+        """ sample_rate of images (default -1) """
+
+        plannar: bool
+        """ Read/write data as plannar, i.e. not interleaved (default True) """
+
+        pipe: sp.Popen
+        """ pipe object to ffmpeg/ffprobe (default None)"""
+
+        frame_size: int
+        """ Weight in bytes of one image (default -1)"""
+
+        filename: str
+        """ Filename of the file (default None)"""
+
+        frame_counter: FrameCounter
+        """ `Framecounter` object to count ellapsed time (default None)"""
+
+    def __init__(self, *, logLevel = 16, debugMode = False):
+        """
+        Create a VideoIO object giving ffmpeg/ffrobe loglevel and defining debug mode
+
+        Parameters
+        ----------
+        log_level: int (default 16)
+            Log level to pass to the underlying ffmpeg/ffprobe command.
+
+        debugMode: bool (default (False)
+            Show debug info. while processing video
+        """
+
+        self.mode = PipeMode.UNK_MODE
+        self.logLevel = logLevel
+        self.debugMode = debugMode
+
+        # Call init() method
+        self.init()
+
+    def init(self):
+        """
+        Init or reinit a VideoIO object.
+        """
+        self.channels  = -1
+        self.sample_rate = -1
+        self.plannar = True
+        self.pipe = None
+        self.frame_size = -1
+        self.filename = None
+        self.frame_counter = None
+
+    _repr_exclude = {"pipe"}
+    """ List of excluded attribute for string conversion. """
+
+    # converting the object to a string representation
+    def __repr__(self):
+        """
+        Convert object (excluding attributes in _repr_exclude) to string representation.
+        """
+        attrs = ", ".join(
+            f"{k}={v!r}"
+            for k, v in self.__dict__.items()
+            if k not in self._repr_exclude
+        )
+        return f"{self.__class__.__name__}({attrs})"
+
+    __str__ = __repr__
+    """ String representation """
+
+    def get_elapsed_time_as_str(self) -> str:
+        """
+        Method to get elapsed time (float value represented) as str.
+
+        Returns
+        ----------
+        str or None
+            Elapsed time (float value) as str, "15.500" for instance for 15 secondes and 500 milliseconds
+            None if no frame counter are available.
+        """
+        if self.frame_counter is None:
+            return None
+        return self.frame_counter.get_elapsed_time_as_str()
+
+    def get_formated_elapsed_time_as_str(self,show_ms=True) -> str:
+        """
+        Method to get elapsed time (hour format) as str.
+
+        Returns
+        ----------
+        str or None
+            Elapsed time (float value) as str, "00:00:15.500" for instance for 15 secondes and 500 milliseconds
+            None if no frame counter are available.
+        """
+        if self.frame_counter is None:
+            return None
+        return self.frame_counter.get_formated_elapsed_time_as_str()
+
+    def get_elapsed_time(self) -> float:
+        """
+        Method to get elapsed time as float value rounded to 3 decimals.
+
+        Returns
+        ----------
+        float or None
+            Elapsed time (float value) as str, 15.500 for instance for 15 secondes and 500 milliseconds
+            None if no frame counter are available.
+        """
+        if self.frame_counter is None:
+            return None
+        return self.frame_counter.get_elapsed_time()
+
+    def is_opened(self) -> bool:
+        """
+        Method to get status of the underlying pipe to ffmpeg.
+
+        Returns
+        ----------
+        bool
+            True if pipe is opened (reading or writing mode), False if not.
+        """
+        # is the pip opened?
+        if self.pipe is not None and self.pipe.poll() is None:
+            return True
+
+        return False
+
+    def close(self):
+        """
+        Method to close current pipe to ffmpeg (if any). Ffmpeg/ffprobe  will be terminated. Object can be reused using open or create methods.
+        """
+        if self.pipe is not None:
+            if self.mode == PipeMode.WRITE_MODE:
+                # killing will make ffmpeg not finish properly the job, close the pipe
+                # to let it know that no more data are comming
+                self.pipe.stdin.close()
+            else: # self.mode == PipeMode.READ_MODE
+                # in read mode, no need to be nice, send SIGTERM on Linux,/Kill it on windows
+                self.pipe.kill()
+
+            # wait for subprocess to end
+            self.pipe.wait()
+
+        # reinit object for later use
+        self.init()
+
+    def create( self, filename, sample_rate, channels, *, writeOverExistingFile = False,
+                outputEncoding = AudioFormat.PCM32LE, encodingParams = None, plannar = True ):
+        """
+        Method to create a audio file using parametrized access through ffmpeg. Importante note: calling create
+        on a AudioIO will close any former open video.
+
+        Parameters
+        ----------
+        filename: str or path
+            filename of path to the file (mp4, avi, ...)
+
+        sample_rate: int
+            If defined as a positive value, sample_rates of the output file will be set to this value.
+
+        channels: int
+            If defined as a positive value, number of channels of output file will be set to this value.
+
+        fps:
+            If defined as a positive value, fps of input video will be set to this value.
+
+        outputEncoding: AudioFormat optional (default AudioFormat.PCM32LE)
+            Define audio format for samples. Possible value is AudioFormat.PCM32LE.
+
+        encodingParams: str optional (default None)
+            Parameter to pass to ffmpeg to encode video like audio filters.
+
+        plannar : bool optionnal (default True)
+            Input data to write are grouped by channel if True, interleaved instead.
+
+        Returns
+        ----------
+        bool
+            Was the creation successfull
+        """
+
+        # Close if already opened
+        self.close()
+
+        # Set geometry/fps of the video stream from params
+        self.sample_rate = int(sample_rate)
+        self.channels = int(channels)
+        self.plannar = plannar
+
+        # Check params
+        if self.sample_rate <= 0 or self.channels <= 0:
+            raise self.AudioIOException("Bad parameters: sample_rate={}, channels={}".format(self.sample_rate,self.channels))
+
+        # To write audio, we do not need to know in advance frame size, we will write x values of n bytes
+        self.frame_size = None
+
+        # Video params are set, open the video
+        cmd = [self.audioProgram] # ffmpeg
+
+        if writeOverExistingFile == True:
+            cmd.extend(['-y'])
+
+        cmd.extend(['-hide_banner',
+            '-nostats',
+            '-loglevel', str(self.logLevel),
+            '-f', 'f32le', '-acodec', outputEncoding.value, # input expected coding
+            '-ar', f"{self.sample_rate}",
+            '-ac', f"{self.channels}",
+            '-i', '-'])
+
+        if encodingParams is not None:
+            cmd.extend(encodingParams.split())
+
+        # remove video
+        cmd.extend( ['-vn', filename ] )
+
+        if self.debugMode == True:
+            print( ' '.join(cmd), file=sys.stderr )
+
+        # store filename and set mode
+        self.filename = filename
+        self.mode = PipeMode.WRITE_MODE
+
+        # try call ffmpeg and write frames directly to pipe
+        try:
+            self.pipe = sp.Popen(cmd, stdin=sp.PIPE)
+            self.frame_counter = FrameCounter(self.sample_rate)
+        except Exception as e:
+            # if pipe failed, reinit object and raise exception
+            self.init()
+            raise
+
+        return True
+
+    def open( self, filename, *, sample_rate = -1, channels = -1, inputEncoding = AudioFormat.PCM32LE,
+                    decodingParams = None, frame_size = 1.0, plannar = True, start_time = 0.0 ):
+        """
+        Method to read (video file containing) audio using parametrized access through ffmpeg. Importante note: calling open
+        on a AudioIO will close any former open file.
+
+        Parameters
+        ----------
+        filename: str or path
+            filename of path to the file (mp4, avi, ...)
+
+        sample_rate: int optional (default -1)
+            If defined as a positive value, sample rate of the input audio will be converted to this value.
+
+        channels: int optional (default -1)
+            If defined as a positive value, number of channels of the input audio will converted to this value.
+
+        inputEncoding: AudioFormat optional (default AudioFormat.PCM32LE)
+            Define audio format for samples. Possible value is AudioFormat.PCM32LE.
+
+        decodingParams: str optional (default None)
+            Parameter to pass to ffmpeg to decode video like audio filters.
+
+        plannar: bool optionnal (default True)
+            Group audio samples per channel if True. Else, samples are interleaved.
+
+        frame_size: int or float (default 1.0)
+            If frame_size is an int, it is the number of expected samples in each frame, for instance 8000 for 8000 samples.
+            if frame_size is a float, it is considered as a time in seconds for each audio frame, for instance 1.0 for 1 second, 0.010 for 10 ms.
+            Number of samples in this case is computed using frame_size and sample_rate as int(frame_size * sample_rate)
+
+        start_time: float optional (default 0.0)
+            Define the reading start time. If not set, reading at beginning of the file.
+
+        Returns
+        ----------
+        bool
+            Was the opening successfull
+        """
+
+        # Close if already opened
+        self.close()
+
+        # Force conversion of parameters
+        channels = int(channels)
+        sample_rate = float(sample_rate)
+
+        self.plannar = plannar
+
+        # get parameters from file if needed:
+        if sample_rate <= 0 or channels <= 0:
+            self.channels, self.sample_rate = self.getAudioParams(filename)
+
+        # check if parameters ask to overide video parameters
+        if channels > 0:
+            self.channels = channels
+        if sample_rate > 0:
+            self.sample_rate = sample_rate
+
+        # check parameters
+
+        if isinstance(frame_size,float):
+            # time in seconds
+            self.frame_size = int(frame_size*self.sample_rate)
+        elif isinstance(frame_size,int):
+            # number of samples
+            self.frame_size = frame_size
+        else:
+            # to do
+            pass
+
+        # Video params are set, open the video
+        cmd = [self.audioProgram, # ffmpeg
+                    '-hide_banner',
+                    '-nostats',
+                    '-loglevel', str(self.logLevel)]
+
+        if decodingParams is not None:
+            cmd.extend([decodingParams.split()])
+
+        if start_time < 0.0:
+            pass
+        elif start_time > 0.0:
+            cmd.extend(["-ss", f"{start_time}"])            
+
+        cmd.extend( ['-i', filename,
+                     '-f', 'f32le', '-acodec', inputEncoding.value, # input expected coding
+                     '-ar', f"{self.sample_rate}",
+                     '-ac', f"{self.channels}",
+                     '-' # output to stdout
+                    ]
+                )
+
+        if self.debugMode == True:
+            print( ' '.join(cmd) )
+
+        # store filename and set mode to READ_MODE
+        self.filename = filename
+        self.mode = PipeMode.READ_MODE
+
+        # try to call ffmpeg to get frames directly from pipe
+        try:
+            self.pipe = sp.Popen(cmd, stdout=sp.PIPE)
+            self.frame_counter = FrameCounter(self.sample_rate)
+            if start_time > 0.0:
+                self.frame_counter += start_time # adding with float means adding time
+        except Exception as e:
+            # if pipe failed, reinit object and raise exception
+            self.init()
+            raise
+
+        return True
+
+    def read_frame(self, with_timestamps = False):
+        """
+        Read next frame from the audio file
+
+        Parameters
+        ----------
+        with_timestamps: bool optional (default False)
+            If set to True, the method returns a ``FrameContainer`` with the audio and an array containing the associated timestamp(s)
+
+        Returns
+        ----------
+        nparray or FrameContainer
+            A frame of shape (self.channels,self.frame_size) as defined in the reader/open call if self.plannar is True. A frame
+            of shape (self.channels*self.frame_size) with interleaved data if self.plannar is False.
+            if with_timestamps is True, the return object is a FrameContainer with the audio data in ``FrameContainer.data`` and
+            the associated timestamp in ``FrameContainer.timestamps`` as an array (one element).
+        """
+
+        if self.pipe is None:
+            raise self.AudioIOException("No pipe opened to {}. Call open(...) before reading a frame.".format(self.audioProgram))
+        # - pipe is in write mode
+        if self.mode != PipeMode.READ_MODE:
+            raise self.AudioIOException("Pipe to {} for '{}' not opened in read mode.".format(self.audioProgram, self.filename))
+
+        if with_timestamps:
+            # get elapsed time in video, it is time of next frame(s)
+            current_elapsed_time = self.get_elapsed_time()
+
+        # read rgb image from pipe
+        toread = self.frame_size*4
+        buffer = self.pipe.stdout.read(toread)
+        if len(buffer) != toread:
+            # not considered as an error, no more frame, no exception
+            return None
+
+        # get numpy UINT8 array from buffer
+        audio = np.frombuffer(buffer, dtype = np.float32).reshape(self.frame_size, self.channels)
+
+        # make it plannar (or not)
+        if self.plannar:
+            #transpose it
+            audio = audio.T
+
+        # increase frame_counter
+        self.frame_counter.frame_count += (self.frame_size * self.channels)
+
+        # say to gc that this buffer is no longer needed
+        del buffer
+
+        if with_timestamps:
+            return FrameContainer(1, audio, self.frame_size/self.sample_rate, current_elapsed_time)
+        
+        return audio
+
+    def read_batch(self, numberOfFrames, with_timestamps = False):
+        """
+        Read next batch of audio from the file
+
+        Parameters
+        ----------
+        number_of_frames: int
+            Number of desired images within the batch. The last batch from the file may have less images.
+            
+        with_timestamps: bool optional (default False)
+            If set to True, the method returns a FrameContainer with the batch and the an array containing the associated timestamps to frames
+
+        Returns
+        ----------
+        nparray or FrameContainer
+            A batch of shape (n, self.channels,self.frame_size) as defined in the reader/open call if self.plannar is True. A batch
+            of shape (n, self.channels*self.frame_size) with interleaved data if self.plannar is False.
+            if with_timestamps is True, the return object is a FrameContainer with the audio batch in ``FrameContainer.data`` and
+            the associated timestamp in ``FrameContainer.timestamps`` as an array (one element for each audio frame).
+        """
+
+        if self.pipe is None:
+            raise self.AudioIOException("No pipe opened to {}. Call open(...) before reading frames.".format(self.audioProgram))
+        # - pipe is in write mode
+        if self.mode != PipeMode.READ_MODE:
+            raise self.AudioIOException("Pipe to {} for '{}' not opened in read mode.".format(self.audioProgram, self.filename))
+
+        if with_timestamps:
+            # get elapsed time in video, it is time of next frame(s)
+            current_elapsed_time = self.get_elapsed_time()
+
+        # try to read complete batch
+        toread = self.frame_size*4*self.channels*numberOfFrames
+        buffer = self.pipe.stdout.read(toread)
+
+        # check if we have at least 1 Frame
+        if len(buffer) < toread:
+            # not considered as an error, no more frame, no exception
+            return None
+
+        # compute actual number of Frames
+        actualNbFrames = len(buffer)//(self.frame_size*4*self.channels)
+
+        # get and reshape batch from buffer
+        batch = np.frombuffer(buffer, dtype = np.float32).reshape((actualNbFrames, self.frame_size, self.channels,))
+
+        if self.plannar:
+            batch = batch.transpose(0, 2, 1)
+
+        # increase frame_counter
+        self.frame_counter.frame_count += (actualNbFrames * self.frame_size * self.channels)
+        
+        # say to gc that this buffer is no longer needed
+        del buffer
+
+        if with_timestamps:
+            return FrameContainer( actualNbFrames, batch, self.frame_size/self.sample_rate, current_elapsed_time)
+        
+        return batch
+
+    def write_frame(self, audio) -> bool:
+        """
+        Write an audio frame to the file
+
+        Parameters
+        ----------
+        audio: nparray
+            The audio frame to write to the video file of shape (self.channels,nb_samples_per_channel) if plannar is True else (self.channels*nb_samples_per_channel).
+
+        Returns
+        ----------
+        bool
+            Writing was successful or not.
+        """
+        # Check params
+        # - pipe exists
+        if self.pipe is None:
+            raise self.AudioIOException("No pipe opened to {}. Call create(...) before writing frames.".format(self.audioProgram))
+        # - pipe is in write mode
+        if self.mode != PipeMode.WRITE_MODE:
+            raise self.AudioIOException("Pipe to {} for '{}' not opened in write mode.".format(self.audioProgram, self.filename))
+        # - shape of image is fine, thus we have pixels for a full compatible frame
+        if audio.shape[0] != self.channels:
+            raise self.AudioIOException("Wong audio shape: {} expected ({},{}).".format(audio.shape,self.channels,self.frame_size))
+        # - type of data is Float32
+        if audio.dtype != np.float32:
+            raise self.AudioIOException("Wong audio type: {} expected np.float32.".format(audio.dtype))
+
+        # array must have a shape (channels, samples), reshape it it to (samples, channels) if plannar
+        if not self.plannar:
+            audio = audio.reshape(-1)
+
+        print( audio.shape )
+
+        # garantee to have a C continuous array
+        if not audio.flags['C_CONTIGUOUS']:
+            a = np.ascontiguousarray(a) 
+
+        # write frame
+        buffer = audio.tobytes()
+        if self.pipe.stdin.write( buffer ) < len(buffer):
+            print( f"Error writing frame to {self.filename}" )
+            return False
+
+        # increase frame_counter
+        self.frame_counter.frame_count += (self.frame_size * self.channels)
+
+        # say to gc that this buffer is no longer needed 
+        del buffer
+
+        return True
+
+    def write_batch(self, batch):
+        """
+        Write a batch of audio frame to the file
+
+        Parameters
+        ----------
+        batch: nparray
+            The batch of audio frames to write to the video file of shape (n,self.channels,nb_samples_per_channel) if plannar is True else (n,self.channels*nb_samples_per_channel) of interleaved audio data.
+
+        Returns
+        ----------
+        bool
+            Writing was successful or not.
+        """
+        # Check params
+        # - pipe exists
+        if self.pipe is None:
+            raise self.AudioIOException("No pipe opened to {}. Call create(...) before writing frames.".format(self.audioProgram))
+        # - pipe is in write mode
+        if self.mode != PipeMode.WRITE_MODE:
+            raise self.AudioIOException("Pipe to {} for '{}' not opened in write mode.".format(self.audioProgram, self.filename))
+        # batch is 3D (n, channels, nb samples)
+        if batch.ndim !=3:
+            raise self.AudioIOException("Wrong batch shape: {} expected 3 dimensions (n, n_channels, n_samples_per_channel).".format(batch.shape))
+        # - shape of images in batch is fine
+        if batch.shape[2] != self.channels:
+            raise self.AudioIOException("Wrong audio channels in batch: {} expected {} {}.".format(batch.shape[2], self.channels, batch.shape))
+
+        # array must have a shape (n * n_channels * n_samples_per_channel) before writing them to pipe
+        # reshape it it to (n * n_channels * n_samples_per_channel) if plannar is False
+        if not self.plannar:
+            # goes from (n, n_channels, n_samples_per_channel) to (n * n_channels * n_samples_per_channel)
+            batch = batch.transpose(0, 2, 1) # first go to (n, n_samples_per_channel, n_channels)
+            batch = batch.reshape(-1) # then to 1D array (n * n_channels * n_samples_per_channel)
+
+        # garantee to have a C continuous array
+        if not batch.flags['C_CONTIGUOUS']:
+            batch = np.ascontiguousarray(batch)
+
+        # write frame
+        buffer = batch.tobytes()
+        if self.pipe.stdin.write( buffer ) < len(buffer):
+            # say to gc that this buffer is no longer needed
+            del buffer
+            raise self.AudioIOException("Error writing batch to '{}'.".format(self.filename))
+
+        # increase frame_counter
+        self.frame_counter.frame_count += int(batch.shape[0]/self.channels) # int conversion is mandatory to avoid confusion with time as float
+              
+        # say to gc that this buffer is no longer needed
+        del buffer
+
+        return True
+
+    def iter_frames(self, with_timestamps = False):
+        """
+        Method to iterate on audio frames using AudioIO obj.
+        for audio_frame in obj.iter_frames():
+            ....
+
+        Parameters
+        ----------
+        with_timestamps: bool optional (default False)
+            If set to True, the method returns a FrameContainer object with the batch and an array containing the associated timestamps to frames
+
+        Returns
+        ----------
+        nparray or FrameContainer
+            A batch of images of shape ()
+        """
+
+        try:
+            if self.mode == PipeMode.READ_MODE:
+                while self.isOpened():
+                    frame = self.readFrame(with_timestamps)
+                    if frame is not None:
+                        yield frame
+        finally:
+            self.close()
+
+    def iter_batches(self, batch_size : int, with_timestamps = False ):
+        """
+        Method to iterate on batch ofaudio  frames using VideoIO obj.
+        for audio_batch in obj.iter_batches():
+            ....
+
+        Parameters
+        ----------
+        with_timestamps: bool optional (default False)
+            If set to True, the method returns a FrameContainer with the batch and the an array containing the associated timestamps to frames
+        """
+        try:
+            if self.mode == PipeMode.READ_MODE:
+                while self.isOpened():
+                    batch = self.readBatch(batch_size, with_timestamps)
+                    if batch is not None:
+                        yield batch
+        finally:
+            self.close()
+
+    # function aliases to be compliant with original C++ version
+    getAudioTimeInSec = get_time_in_sec
+    getAudioParams = get_params
+    get_audio_time_in_sec = get_time_in_sec
+    get_audio_params = get_params
+    isOpened = is_opened
+    readFrame = read_frame
+    readBatch = read_batch
+    writeFrame = write_frame
+    writeBatch = write_batch
+