Skip to content

AudioClip

class vidiopy.AudioClip

Bases: vidiopy.Clip

The AudioClip class represents an audio clip. It is a subclass of the Clip class.

Parameters:
  • duration (int or float, optional): The duration of the audio clip. Defaults to None.
  • fps (int, optional): Frames per second of the audio clip. Defaults to None.
Attributes:
  • fps: int | None: The frames per second of the audio clip. Defaults to fps Parameter.
  • _original_dur: int | float | None: The original duration of the audio clip. Defaults to duration Parameter.
  • _audio_data: np.ndarray | None: The audio data of the clip. Defaults to None.
  • channels: int | None: The number of audio channels. Defaults to None.
  • _st: int | float: The start time of the audio clip. Defaults to 0.0.
  • _ed: int | float | None: The end time of the audio clip. Defaults to duration Parameter.
Properties:

audio_data: np.ndarray

This property gets the audio data. If the audio data is not set, it raises a ValueError.

Returns:
np.ndarray: The audio data.
Raises:
ValueError: If the audio data is not set.

Example: : 

>>> clip = AudioClip()
>>> clip.audio_data = np.array([1, 2, 3])
>>> print(clip.audio_data)
array([1, 2, 3])

duration: int | float

This property gets the duration of the audio clip. The duration is represented in seconds and can be an integer, a float, or None if the duration is not set.

Note:
You Can't Set the duration of the audio clip it is not allowed to change directly.

Raises: AttributeError: Always raises an AttributeError if you try to set duration.

Returns:
int | float: The duration of the audio clip.

Example: : 

>>> clip = AudioClip(duration=10)
>>> print(clip.duration)
10

start: int | float

This property gets the start time of the audio clip. The start time is represented in seconds and can be an integer or a float.

Returns:
int | float: The start time of the audio clip.

Example: : 

>>> clip = AudioClip()
>>> print(clip.start)
0.0
>>> clip.start = 5
>>> print(clip.start)
5

end: int | float | None

This property gets the end time of the audio clip. The end time is represented in seconds and can be an integer, a float, or None if the end time is not set.

Returns:
int | float | None: The end time of the audio clip.

Example: : 

>>> clip = AudioClip(duration=10)
>>> print(clip.end)
10
>>> clip.end = 5
>>> print(clip.end)
5

Methods:

def set_data(self, audio_data: np.ndarray) -> Self:

This method sets the audio data and returns the instance of the class.

Args:
audio_data (np.ndarray): The audio data to set.
Returns:
AudioClip: The instance of the class.

Example: : 

    >>> clip = AudioClip()
    >>> clip.set_data(np.array([1, 2, 3]))
    >>> print(clip.audio_data)
    array([1, 2, 3])

def set_fps(self, fps: int | None) -> Self:

This method sets the frames per second (fps) for the audio clip and returns the instance of the class.

Args:
fps: int | None: The frames per second to set. If None, the fps will be unset.
Returns:
AudioClip: Self The Instance of the class.

Example: : 

>>> clip = AudioClip()
>>> clip.set_fps(30)
>>> print(clip.fps)
30

def set_start(self, start: int | float) -> Self:

This method sets the start time of the audio clip and returns the instance of the class. The start time is represented in seconds and can be an integer or a float.

Args:
start: int | float: The start time to set in seconds.
Returns:
AudioClip: The instance of the class with the updated start time.

Example: : 

>>> clip = AudioClip()
>>> clip.set_start(5)
>>> print(clip.start)
5

def set_end(self, end: int | float | None) -> Self:

This method sets the end time of the audio clip and returns the instance of the class. The end time is represented in seconds and can be an integer, a float, or None if the end time is not to be set.

Args:
end: int | float | None: The end time to set in seconds.
Returns:
AudioClip: The instance of the class with the updated end time.

Example: : 

>>> clip = AudioClip()
>>> clip.set_end(10)
>>> print(clip.end)
10

def get_frame_at_t(self, t: int | float) -> np.ndarray:

This method gets the audio frame at a specific time t. The time t is represented in seconds and can be an integer or a float. It calculates the frame index using the duration, total frames, and time t, and returns the audio data at that frame index.

Args:
t: int | float: The time in seconds at which to get the audio frame.
Returns:
np.ndarray: The audio data at the specified time.
Raises:
ValueError: If frames per second (fps) is not set, audio data is not set, or original duration is not set.

def iterate_frames_at_fps(self, fps: int | float | None = None) -> Generator[np.ndarray, None, None]:

This method generates audio frames at a specific frames per second (fps) rate. If no fps is provided, it uses the fps set in the AudioClip instance. It calculates the original fps using the duration and total frames, then generates frames at the specified fps rate.

Args:
fps (int | float | None, optional): The frames per second rate at which to generate frames. If not provided, the fps set in the AudioClip instance is used.
Yields:
np.ndarray: The audio data at each frame.
Raises:
ValueError: If frames per second (fps) is not set, audio data is not set, or original duration is not set.

def iterate_all_frames(self) -> Generator[np.ndarray, None, None]:

This method generates all audio frames in the AudioClip instance. It iterates over each frame in the audio data and yields it.

Yields:
np.ndarray: The audio data at each frame.
Raises:
ValueError: If audio data is not set.

def fl_frame_transform(self, func, *args, **kwargs) -> Self:

This method applies a function to each frame of the audio data. The function should take a frame (an ndarray of channel data) as its first argument, followed by any number of additional positional and keyword arguments.

Args:
  • func (Callable): The function to apply to each frame. It should take a frame (an ndarray of channel data) as its first argument.
  • *args: Additional positional arguments to pass to the function.
  • **kwargs: Additional keyword arguments to pass to the function.
Returns:
AudioClip: The instance of the class with the transformed audio data.
Raises:
ValueError: If audio data is not set.

def fl_clip_transform(self, func, *args, **kwargs) -> Self:

This method applies a function to the entire audio data. The function should take the AudioClip instance as its first argument, followed by any number of additional positional and keyword arguments.

Args:
  • func (Callable): The function to apply to the audio data. It should take the AudioClip instance as its first argument.
  • *args: Additional positional arguments to pass to the function.
  • **kwargs: Additional keyword arguments to pass to the function.
Returns:
AudioClip: The instance of the class with the transformed audio data.
Raises:
ValueError: If audio data is not set.

def fl_time_transform(self, func: Callable[[int | float], int | float]) -> Self:

This method applies a time transformation function to the get_frame_at_t method of the AudioClip instance. The transformation function should take a time (an integer or a float) as its argument and return a transformed time.

The get_frame_at_t method is replaced with a new method that applies the transformation function to its argument before calling the original method.

Args:
func (Callable[[int | float], int | float]): The time transformation function to apply. It should take a time (an integer or a float) as its argument and return a transformed time.
Returns:
AudioClip: The instance of the class with the transformed get_frame_at_t method.
Raises:
ValueError: If the get_frame_at_t method is not set.

def sub_clip_copy(self, start: float | int | None = None, end: float | int | None = None) -> Self

This method creates a copy of the AudioClip instance and then creates a subclip from the audio clip starting from start to end in the copied instance. If start or end is not provided, it uses the start or end time set in the AudioClip instance. If neither is set, it uses 0 for start and the duration for end.

It calculates the original frames per second (fps) using the duration and total frames, then calculates the start and end frame indices using the original fps. It then updates the audio data, original duration, end time, and start time of the copied AudioClip instance.

Args:
  • start (float | int | None, optional): The start time of the subclip in seconds. If not provided, the start time set in the AudioClip instance is used. Defaults to None.
  • end (float | int | None, optional): The end time of the subclip in seconds. If not provided, the end time set in the AudioClip instance is used. Defaults to None.
Returns:
AudioClip: A copy of the instance of the class with the updated audio data, original duration, end time, and start time.
Raises:
ValueError: If audio data is not set, original duration is not set, or end time is greater than the original duration.

def copy(self) -> Self:

This method creates a deep copy of the AudioClip instance and returns it. It uses the copy_ function, which should be a deep copy function like copy.deepcopy in Python's standard library.
Returns:
AudioClip: A deep copy of the instance of the class.
Raises:
ValueError: If the copy_ function is not set or does not correctly create a deep copy.
> def write_audiofile(self, path: str, fps: int | None = None, overwrite=True, show_log=False, **kwargs) -> None:

This method writes the audio data to an audio file at the specified path. It uses the frames per second (fps) if provided, otherwise it uses the fps set in the AudioClip instance. It raises a ValueError if fps is not set in either way. It also raises a ValueError if audio data, original duration, or channels are not set.

It creates a temporary audio data array by getting the frame at each time step from 0 to the end or duration with a step of 1/fps. It then writes the temporary audio data to the audio file using the ffmpegio.audio.write function.

Args:
  • path (str): The path to write the audio file to.
  • fps (int | None, optional): The frames per second to use. If not provided, the fps set in the AudioClip instance is used. Defaults to None.
  • overwrite (bool, optional): Whether to overwrite the audio file if it already exists. Defaults to True.
  • show_log (bool, optional): Whether to show the log of the ffmpegio.audio.write function. Defaults to False.
  • **kwargs: Additional keyword arguments to pass to the ffmpegio.audio.write function.
Raises:
ValueError: If fps is not set, audio data is not set, original duration is not set, or channels are not set.

Comments