AudioClip

AudioClip

class moviepy.audio.AudioClip.AudioClip(make_frame=None, duration=None, fps=None)

Bases: moviepy.Clip.Clip

Base class for audio clips.

See AudioFileClip and CompositeSoundClip for usable classes.

An AudioClip is a Clip with a make_frame attribute of the form `` t -> [ f_t ]`` for mono sound and t-> [ f1_t, f2_t ] for stereo sound (the arrays are Numpy arrays). The f_t are floats between -1 and 1. These bounds can be trespassed without problems (the program will put the sound back into the bounds at conversion time, without much impact).

Parameters:

make_frame

A function t-> frame at time t. The frame does not mean much for a sound, it is just a float. What ‘makes’ the sound are the variations of that float in the time.

duration

Duration of the clip (in seconds). Some clips are infinite, in this case their duration will be None.

nchannels

Number of channels (one or two for mono or stereo).

Examples

>>> # Plays the note A in mono (a sine wave of frequency 440 Hz)
>>> import numpy as np
>>> make_frame = lambda t: np.sin(440 * 2 * np.pi * t)
>>> clip = AudioClip(make_frame, duration=5, fps=44100)
>>> clip.preview()

>>> # Plays the note A in stereo (two sine waves of frequencies 440 and 880 Hz)
>>> make_frame = lambda t: np.array([
...     np.sin(440 * 2 * np.pi * t),
...     np.sin(880 * 2 * np.pi * t)
... ]).T.copy(order="C")
>>> clip = AudioClip(make_frame, duration=3, fps=44100)
>>> clip.preview()

audio_delay(offset=0.2, n_repeats=8, decay=1)

Repeats audio certain number of times at constant intervals multiplying their volume levels using a linear space in the range 1 to decay argument value.

Parameters:

offsetfloat, optional

Gap between repetitions start times, in seconds.

n_repeatsint, optional

Number of repetitions (without including the clip itself).

decayfloat, optional

Multiplication factor for the volume level of the last repetition. Each repetition will have a value in the linear function between 1 and this value, increasing or decreasing constantly. Keep in mind that the last repetition will be muted if this is 0, and if is greater than 1, the volume will increase for each repetition.

Examples

>>> from moviepy import *
>>> videoclip = AudioFileClip('myaudio.wav').fx(
...     audio_delay, offset=.2, n_repeats=10, decayment=.2
... )

>>> # stereo A note
>>> make_frame = lambda t: np.array(
...     [np.sin(440 * 2 * np.pi * t), np.sin(880 * 2 * np.pi * t)]
... ).T
... clip = AudioClip(make_frame=make_frame, duration=0.1, fps=44100)
... clip = audio_delay(clip, offset=.2, n_repeats=11, decay=0)

audio_fadein(duration)

Return an audio (or video) clip that is first mute, then the sound arrives progressively over duration seconds.

Parameters:

durationfloat

How long does it take for the sound to return to its normal level.

Examples

>>> clip = VideoFileClip("media/chaplin.mp4")
>>> clip.fx(audio_fadein, "00:00:06")

audio_fadeout(duration)

Return a sound clip where the sound fades out progressively over duration seconds at the end of the clip.

Parameters:

durationfloat

How long does it take for the sound to reach the zero level at the end of the clip.

Examples

>>> clip = VideoFileClip("media/chaplin.mp4")
>>> clip.fx(audio_fadeout, "00:00:06")

audio_loop(n_loops=None, duration=None)

Loops over an audio clip.

Returns an audio clip that plays the given clip either n_loops times, or during duration seconds.

Examples

>>> from moviepy import *
>>> videoclip = VideoFileClip('myvideo.mp4')
>>> music = AudioFileClip('music.ogg')
>>> audio = afx.audio_loop( music, duration=videoclip.duration)
>>> videoclip.with_audio(audio)

audio_normalize()

Return a clip whose volume is normalized to 0db.

Return an audio (or video) clip whose audio volume is normalized so that the maximum volume is at 0db, the maximum achievable volume.

Examples

>>> from moviepy import *
>>> videoclip = VideoFileClip('myvideo.mp4').fx(afx.audio_normalize)

close()

Release any resources that are in use.

copy()

Allows the usage of .copy() in clips as chained methods invocation.

cutout(start_time, end_time)

Returns a clip playing the content of the current clip but skips the extract between start_time and end_time, which can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’.

If the original clip has a duration attribute set, the duration of the returned clip is automatically computed as `` duration - (end_time - start_time)``.

The resulting clip’s audio and mask will also be cutout if they exist.

Parameters:

start_timefloat or tuple or str

Moment from which frames will be ignored in the resulting output.

end_timefloat or tuple or str

Moment until which frames will be ignored in the resulting output.

fx(func, *args, **kwargs)

Returns the result of func(self, *args, **kwargs), for instance

>>> new_clip = clip.fx(resize, 0.2, method="bilinear")

is equivalent to

>>> new_clip = resize(clip, 0.2, method="bilinear")

The motivation of fx is to keep the name of the effect near its parameters when the effects are chained:

>>> from moviepy.video.fx import multiply_volume, resize, mirrorx
>>> clip.fx(multiply_volume, 0.5).fx(resize, 0.3).fx(mirrorx)
>>> # Is equivalent, but clearer than
>>> mirrorx(resize(multiply_volume(clip, 0.5), 0.3))

get_frame(t)

Gets a numpy array representing the RGB picture of the clip, or (mono or stereo) value for a sound clip, at time t.

Parameters:

tfloat or tuple or str

Moment of the clip whose frame will be returned.

is_playing(t)

If t is a time, returns true if t is between the start and the end of the clip. t can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’. If t is a numpy array, returns False if none of the t is in the clip, else returns a vector [b_1, b_2, b_3…] where b_i is true if tti is in the clip.

iter_chunks(chunksize=None, chunk_duration=None, fps=None, quantize=False, nbytes=2, logger=None)

Iterator that returns the whole sound array of the clip by chunks

iter_frames(fps=None, with_times=False, logger=None, dtype=None)

Iterates over all the frames of the clip.

Returns each frame of the clip as a HxWxN Numpy array, where N=1 for mask clips and N=3 for RGB clips.

This function is not really meant for video editing. It provides an easy way to do frame-by-frame treatment of a video, for fields like science, computer vision…

Parameters:

fpsint, optional

Frames per second for clip iteration. Is optional if the clip already has a fps attribute.

with_timesbool, optional

Ff True yield tuples of (t, frame) where t is the current time for the frame, otherwise only a frame object.

loggerstr, optional

Either "bar" for progress bar or None or any Proglog logger.

dtypetype, optional

Type to cast Numpy array frames. Use dtype="uint8" when using the pictures to write video, images…

Examples

>>> # prints the maximum of red that is contained
>>> # on the first line of each frame of the clip.
>>> from moviepy import VideoFileClip
>>> myclip = VideoFileClip('myvideo.mp4')
>>> print ( [frame[0,:,0].max()
             for frame in myclip.iter_frames()])

loop(n=None, duration=None)

Returns a clip that plays the current clip in an infinite loop. Ideal for clips coming from GIFs.

Parameters:

n

Number of times the clip should be played. If None the the clip will loop indefinitely (i.e. with no set duration).

duration

Total duration of the clip. Can be specified instead of n.

max_volume(stereo=False, chunksize=50000, logger=None)

Returns the maximum volume level of the clip.

multiply_stereo_volume(left=1, right=1)

For a stereo audioclip, this function enables to change the volume of the left and right channel separately (with the factors left and right). Makes a stereo audio clip in which the volume of left and right is controllable.

Examples

>>> from moviepy import AudioFileClip
>>> music = AudioFileClip('music.ogg')
>>> audio_r = music.multiply_stereo_volume(left=0, right=1)  # mute left channel/s
>>> audio_h = music.multiply_stereo_volume(left=0.5, right=0.5)  # half audio

multiply_volume(factor, start_time=None, end_time=None)

Returns a clip with audio volume multiplied by the value factor. Can be applied to both audio and video clips.

Parameters:

factorfloat

Volume multiplication factor.

start_timefloat, optional

Time from the beginning of the clip until the volume transformation begins to take effect, in seconds. By default at the beginning.

end_timefloat, optional

Time from the beginning of the clip until the volume transformation ends to take effect, in seconds. By default at the end.

Examples

>>> from moviepy import AudioFileClip
>>>
>>> music = AudioFileClip('music.ogg')
>>> doubled_audio_clip = clip.multiply_volume(2)  # doubles audio volume
>>> half_audio_clip = clip.multiply_volume(0.5)  # half audio
>>>
>>> # silenced clip during one second at third
>>> silenced_clip = clip.multiply_volume(0, start_time=2, end_time=3)

preview(*args, **kwargs)

NOT AVAILABLE: clip.preview requires importing from moviepy.editor

subclip(start_time=0, end_time=None)

Returns a clip playing the content of the current clip between times start_time and end_time, which can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’.

The mask and audio of the resulting subclip will be subclips of mask and audio the original clip, if they exist.

Parameters:

start_timefloat or tuple or str, optional

Moment that will be chosen as the beginning of the produced clip. If is negative, it is reset to clip.duration + start_time.

end_timefloat or tuple or str, optional

Moment that will be chosen as the end of the produced clip. If not provided, it is assumed to be the duration of the clip (potentially infinite). If is negative, it is reset to clip.duration + end_time. For instance:

>>> # cut the last two seconds of the clip:
>>> new_clip = clip.subclip(0, -2)

If end_time is provided or if the clip has a duration attribute, the duration of the returned clip is set automatically.

time_transform(time_func, apply_to=None, keep_duration=False)

Returns a Clip instance playing the content of the current clip but with a modified timeline, time t being replaced by another time time_func(t).

Parameters:

time_funcfunction

A function t -> new_t.

apply_to{“mask”, “audio”, [“mask”, “audio”]}, optional

Can be either ‘mask’, or ‘audio’, or [‘mask’,’audio’]. Specifies if the filter transform should also be applied to the audio or the mask of the clip, if any.

keep_durationbool, optional

False (default) if the transformation modifies the duration of the clip.

Examples

>>> # plays the clip (and its mask and sound) twice faster
>>> new_clip = clip.time_transform(lambda t: 2*t, apply_to=['mask', 'audio'])
>>>
>>> # plays the clip starting at t=3, and backwards:
>>> new_clip = clip.time_transform(lambda t: 3-t)

to_soundarray(tt=None, fps=None, quantize=False, nbytes=2, buffersize=50000)

Transforms the sound into an array that can be played by pygame or written in a wav file. See AudioClip.preview.

Parameters:

fps

Frame rate of the sound for the conversion. 44100 for top quality.

nbytes

Number of bytes to encode the sound: 1 for 8bit sound, 2 for 16bit, 4 for 32bit sound.

transform(func, apply_to=None, keep_duration=True)

General processing of a clip.

Returns a new Clip whose frames are a transformation (through function func) of the frames of the current clip.

Parameters:

funcfunction

A function with signature (gf,t -> frame) where gf will represent the current clip’s get_frame method, i.e. gf is a function (t->image). Parameter t is a time in seconds, frame is a picture (=Numpy array) which will be returned by the transformed clip (see examples below).

apply_to{“mask”, “audio”, [“mask”, “audio”]}, optional

Can be either 'mask', or 'audio', or ['mask','audio']. Specifies if the filter should also be applied to the audio or the mask of the clip, if any.

keep_durationbool, optional

Set to True if the transformation does not change the duration of the clip.

Examples

In the following new_clip a 100 pixels-high clip whose video content scrolls from the top to the bottom of the frames of clip at 50 pixels per second.

>>> filter = lambda get_frame,t : get_frame(t)[int(t):int(t)+50, :]
>>> new_clip = clip.transform(filter, apply_to='mask')

with_duration(duration, change_end=True)

Returns a copy of the clip, with the duration attribute set to t, which can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’. Also sets the duration of the mask and audio, if any, of the returned clip.

If change_end is False, the start attribute of the clip will be modified in function of the duration and the preset end of the clip.

Parameters:

durationfloat

New duration attribute value for the clip.

change_endbool, optional

If True, the end attribute value of the clip will be adjusted accordingly to the new duration using clip.start + duration.

with_end(t)

Returns a copy of the clip, with the end attribute set to t, which can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’. Also sets the duration of the mask and audio, if any, of the returned clip.

Parameters:

tfloat or tuple or str

New end attribute value for the clip.

with_fps(fps, change_duration=False)

Returns a copy of the clip with a new default fps for functions like write_videofile, iterframe, etc.

Parameters:

fpsint

New fps attribute value for the clip.

change_durationbool, optional

If change_duration=True, then the video speed will change to match the new fps (conserving all frames 1:1). For example, if the fps is halved in this mode, the duration will be doubled.

with_is_mask(is_mask)

Says whether the clip is a mask or not.

Parameters:

is_maskbool

New is_mask attribute value for the clip.

with_make_frame(make_frame)

Sets a make_frame attribute for the clip. Useful for setting arbitrary/complicated videoclips.

Parameters:

make_framefunction

New frame creator function for the clip.

with_memoize(memoize)

Sets whether the clip should keep the last frame read in memory.

Parameters:

memoizebool

Indicates if the clip should keep the last frame read in memory.

with_start(t, change_end=True)

Returns a copy of the clip, with the start attribute set to t, which can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’.

These changes are also applied to the audio and mask clips of the current clip, if they exist.

Parameters:

tfloat or tuple or str

New start attribute value for the clip.

change_endbool optional

Indicates if the end attribute value must be changed accordingly, if possible. If change_end=True and the clip has a duration attribute, the end attribute of the clip will be updated to start + duration. If change_end=False and the clip has a end attribute, the duration attribute of the clip will be updated to end - start.

write_audiofile(filename, fps=None, nbytes=2, buffersize=2000, codec=None, bitrate=None, ffmpeg_params=None, write_logfile=False, logger='bar')

Writes an audio file from the AudioClip.

Parameters:

filename

Name of the output file, as a string or a path-like object.

fps

Frames per second. If not set, it will try default to self.fps if already set, otherwise it will default to 44100.

nbytes

Sample width (set to 2 for 16-bit sound, 4 for 32-bit sound)

codec

Which audio codec should be used. If None provided, the codec is determined based on the extension of the filename. Choose ‘pcm_s16le’ for 16-bit wav and ‘pcm_s32le’ for 32-bit wav.

bitrate

Audio bitrate, given as a string like ‘50k’, ‘500k’, ‘3000k’. Will determine the size and quality of the output file. Note that it mainly an indicative goal, the bitrate won’t necessarily be the this in the output file.

ffmpeg_params

Any additional parameters you would like to pass, as a list of terms, like [‘-option1’, ‘value1’, ‘-option2’, ‘value2’]

write_logfile

If true, produces a detailed logfile named filename + ‘.log’ when writing the file

logger

Either "bar" for progress bar or None or any Proglog logger.

AudioFileClip

class moviepy.audio.io.AudioFileClip.AudioFileClip(filename, decode_file=False, buffersize=200000, nbytes=2, fps=44100)

Bases: moviepy.audio.AudioClip.AudioClip

An audio clip read from a sound file, or an array. The whole file is not loaded in memory. Instead, only a portion is read and stored in memory. this portion includes frames before and after the last frames read, so that it is fast to read the sound backward and forward.

Parameters:

filename

Either a soundfile name (of any extension supported by ffmpeg) as a string or a path-like object, or an array representing a sound. If the soundfile is not a .wav, it will be converted to .wav first, using the fps and bitrate arguments.

buffersize:

Size to load in memory (in number of frames)

Examples

>>> snd = AudioFileClip("song.wav")
>>> snd.close()

Attributes:

nbytes

Number of bits per frame of the original audio file.

fps

Number of frames per second in the audio file

buffersize

See Parameters.

audio_delay(offset=0.2, n_repeats=8, decay=1)

Repeats audio certain number of times at constant intervals multiplying their volume levels using a linear space in the range 1 to decay argument value.

Parameters:

offsetfloat, optional

Gap between repetitions start times, in seconds.

n_repeatsint, optional

Number of repetitions (without including the clip itself).

decayfloat, optional

Multiplication factor for the volume level of the last repetition. Each repetition will have a value in the linear function between 1 and this value, increasing or decreasing constantly. Keep in mind that the last repetition will be muted if this is 0, and if is greater than 1, the volume will increase for each repetition.

Examples

>>> from moviepy import *
>>> videoclip = AudioFileClip('myaudio.wav').fx(
...     audio_delay, offset=.2, n_repeats=10, decayment=.2
... )

>>> # stereo A note
>>> make_frame = lambda t: np.array(
...     [np.sin(440 * 2 * np.pi * t), np.sin(880 * 2 * np.pi * t)]
... ).T
... clip = AudioClip(make_frame=make_frame, duration=0.1, fps=44100)
... clip = audio_delay(clip, offset=.2, n_repeats=11, decay=0)

audio_fadein(duration)

Return an audio (or video) clip that is first mute, then the sound arrives progressively over duration seconds.

Parameters:

durationfloat

How long does it take for the sound to return to its normal level.

Examples

>>> clip = VideoFileClip("media/chaplin.mp4")
>>> clip.fx(audio_fadein, "00:00:06")

audio_fadeout(duration)

Return a sound clip where the sound fades out progressively over duration seconds at the end of the clip.

Parameters:

durationfloat

How long does it take for the sound to reach the zero level at the end of the clip.

Examples

>>> clip = VideoFileClip("media/chaplin.mp4")
>>> clip.fx(audio_fadeout, "00:00:06")

audio_loop(n_loops=None, duration=None)

Loops over an audio clip.

Returns an audio clip that plays the given clip either n_loops times, or during duration seconds.

Examples

>>> from moviepy import *
>>> videoclip = VideoFileClip('myvideo.mp4')
>>> music = AudioFileClip('music.ogg')
>>> audio = afx.audio_loop( music, duration=videoclip.duration)
>>> videoclip.with_audio(audio)

audio_normalize()

Return a clip whose volume is normalized to 0db.

Return an audio (or video) clip whose audio volume is normalized so that the maximum volume is at 0db, the maximum achievable volume.

Examples

>>> from moviepy import *
>>> videoclip = VideoFileClip('myvideo.mp4').fx(afx.audio_normalize)

close()

Close the internal reader.

copy()

Allows the usage of .copy() in clips as chained methods invocation.

cutout(start_time, end_time)

Returns a clip playing the content of the current clip but skips the extract between start_time and end_time, which can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’.

If the original clip has a duration attribute set, the duration of the returned clip is automatically computed as `` duration - (end_time - start_time)``.

The resulting clip’s audio and mask will also be cutout if they exist.

Parameters:

start_timefloat or tuple or str

Moment from which frames will be ignored in the resulting output.

end_timefloat or tuple or str

Moment until which frames will be ignored in the resulting output.

fx(func, *args, **kwargs)

Returns the result of func(self, *args, **kwargs), for instance

>>> new_clip = clip.fx(resize, 0.2, method="bilinear")

is equivalent to

>>> new_clip = resize(clip, 0.2, method="bilinear")

The motivation of fx is to keep the name of the effect near its parameters when the effects are chained:

>>> from moviepy.video.fx import multiply_volume, resize, mirrorx
>>> clip.fx(multiply_volume, 0.5).fx(resize, 0.3).fx(mirrorx)
>>> # Is equivalent, but clearer than
>>> mirrorx(resize(multiply_volume(clip, 0.5), 0.3))

get_frame(t)

Gets a numpy array representing the RGB picture of the clip, or (mono or stereo) value for a sound clip, at time t.

Parameters:

tfloat or tuple or str

Moment of the clip whose frame will be returned.

is_playing(t)

If t is a time, returns true if t is between the start and the end of the clip. t can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’. If t is a numpy array, returns False if none of the t is in the clip, else returns a vector [b_1, b_2, b_3…] where b_i is true if tti is in the clip.

iter_chunks(chunksize=None, chunk_duration=None, fps=None, quantize=False, nbytes=2, logger=None)

Iterator that returns the whole sound array of the clip by chunks

iter_frames(fps=None, with_times=False, logger=None, dtype=None)

Iterates over all the frames of the clip.

Returns each frame of the clip as a HxWxN Numpy array, where N=1 for mask clips and N=3 for RGB clips.

This function is not really meant for video editing. It provides an easy way to do frame-by-frame treatment of a video, for fields like science, computer vision…

Parameters:

fpsint, optional

Frames per second for clip iteration. Is optional if the clip already has a fps attribute.

with_timesbool, optional

Ff True yield tuples of (t, frame) where t is the current time for the frame, otherwise only a frame object.

loggerstr, optional

Either "bar" for progress bar or None or any Proglog logger.

dtypetype, optional

Type to cast Numpy array frames. Use dtype="uint8" when using the pictures to write video, images…

Examples

>>> # prints the maximum of red that is contained
>>> # on the first line of each frame of the clip.
>>> from moviepy import VideoFileClip
>>> myclip = VideoFileClip('myvideo.mp4')
>>> print ( [frame[0,:,0].max()
             for frame in myclip.iter_frames()])

loop(n=None, duration=None)

Returns a clip that plays the current clip in an infinite loop. Ideal for clips coming from GIFs.

Parameters:

n

Number of times the clip should be played. If None the the clip will loop indefinitely (i.e. with no set duration).

duration

Total duration of the clip. Can be specified instead of n.

max_volume(stereo=False, chunksize=50000, logger=None)

Returns the maximum volume level of the clip.

multiply_stereo_volume(left=1, right=1)

For a stereo audioclip, this function enables to change the volume of the left and right channel separately (with the factors left and right). Makes a stereo audio clip in which the volume of left and right is controllable.

Examples

>>> from moviepy import AudioFileClip
>>> music = AudioFileClip('music.ogg')
>>> audio_r = music.multiply_stereo_volume(left=0, right=1)  # mute left channel/s
>>> audio_h = music.multiply_stereo_volume(left=0.5, right=0.5)  # half audio

multiply_volume(factor, start_time=None, end_time=None)

Returns a clip with audio volume multiplied by the value factor. Can be applied to both audio and video clips.

Parameters:

factorfloat

Volume multiplication factor.

start_timefloat, optional

Time from the beginning of the clip until the volume transformation begins to take effect, in seconds. By default at the beginning.

end_timefloat, optional

Time from the beginning of the clip until the volume transformation ends to take effect, in seconds. By default at the end.

Examples

>>> from moviepy import AudioFileClip
>>>
>>> music = AudioFileClip('music.ogg')
>>> doubled_audio_clip = clip.multiply_volume(2)  # doubles audio volume
>>> half_audio_clip = clip.multiply_volume(0.5)  # half audio
>>>
>>> # silenced clip during one second at third
>>> silenced_clip = clip.multiply_volume(0, start_time=2, end_time=3)

preview(*args, **kwargs)

NOT AVAILABLE: clip.preview requires importing from moviepy.editor

subclip(start_time=0, end_time=None)

Returns a clip playing the content of the current clip between times start_time and end_time, which can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’.

The mask and audio of the resulting subclip will be subclips of mask and audio the original clip, if they exist.

Parameters:

start_timefloat or tuple or str, optional

Moment that will be chosen as the beginning of the produced clip. If is negative, it is reset to clip.duration + start_time.

end_timefloat or tuple or str, optional

Moment that will be chosen as the end of the produced clip. If not provided, it is assumed to be the duration of the clip (potentially infinite). If is negative, it is reset to clip.duration + end_time. For instance:

>>> # cut the last two seconds of the clip:
>>> new_clip = clip.subclip(0, -2)

If end_time is provided or if the clip has a duration attribute, the duration of the returned clip is set automatically.

time_transform(time_func, apply_to=None, keep_duration=False)

Returns a Clip instance playing the content of the current clip but with a modified timeline, time t being replaced by another time time_func(t).

Parameters:

time_funcfunction

A function t -> new_t.

apply_to{“mask”, “audio”, [“mask”, “audio”]}, optional

Can be either ‘mask’, or ‘audio’, or [‘mask’,’audio’]. Specifies if the filter transform should also be applied to the audio or the mask of the clip, if any.

keep_durationbool, optional

False (default) if the transformation modifies the duration of the clip.

Examples

>>> # plays the clip (and its mask and sound) twice faster
>>> new_clip = clip.time_transform(lambda t: 2*t, apply_to=['mask', 'audio'])
>>>
>>> # plays the clip starting at t=3, and backwards:
>>> new_clip = clip.time_transform(lambda t: 3-t)

to_soundarray(tt=None, fps=None, quantize=False, nbytes=2, buffersize=50000)

Transforms the sound into an array that can be played by pygame or written in a wav file. See AudioClip.preview.

Parameters:

fps

Frame rate of the sound for the conversion. 44100 for top quality.

nbytes

Number of bytes to encode the sound: 1 for 8bit sound, 2 for 16bit, 4 for 32bit sound.

transform(func, apply_to=None, keep_duration=True)

General processing of a clip.

Returns a new Clip whose frames are a transformation (through function func) of the frames of the current clip.

Parameters:

funcfunction

A function with signature (gf,t -> frame) where gf will represent the current clip’s get_frame method, i.e. gf is a function (t->image). Parameter t is a time in seconds, frame is a picture (=Numpy array) which will be returned by the transformed clip (see examples below).

apply_to{“mask”, “audio”, [“mask”, “audio”]}, optional

Can be either 'mask', or 'audio', or ['mask','audio']. Specifies if the filter should also be applied to the audio or the mask of the clip, if any.

keep_durationbool, optional

Set to True if the transformation does not change the duration of the clip.

Examples

In the following new_clip a 100 pixels-high clip whose video content scrolls from the top to the bottom of the frames of clip at 50 pixels per second.

>>> filter = lambda get_frame,t : get_frame(t)[int(t):int(t)+50, :]
>>> new_clip = clip.transform(filter, apply_to='mask')

with_duration(duration, change_end=True)

Returns a copy of the clip, with the duration attribute set to t, which can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’. Also sets the duration of the mask and audio, if any, of the returned clip.

If change_end is False, the start attribute of the clip will be modified in function of the duration and the preset end of the clip.

Parameters:

durationfloat

New duration attribute value for the clip.

change_endbool, optional

If True, the end attribute value of the clip will be adjusted accordingly to the new duration using clip.start + duration.

with_end(t)

Returns a copy of the clip, with the end attribute set to t, which can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’. Also sets the duration of the mask and audio, if any, of the returned clip.

Parameters:

tfloat or tuple or str

New end attribute value for the clip.

with_fps(fps, change_duration=False)

Returns a copy of the clip with a new default fps for functions like write_videofile, iterframe, etc.

Parameters:

fpsint

New fps attribute value for the clip.

change_durationbool, optional

If change_duration=True, then the video speed will change to match the new fps (conserving all frames 1:1). For example, if the fps is halved in this mode, the duration will be doubled.

with_is_mask(is_mask)

Says whether the clip is a mask or not.

Parameters:

is_maskbool

New is_mask attribute value for the clip.

with_make_frame(make_frame)

Sets a make_frame attribute for the clip. Useful for setting arbitrary/complicated videoclips.

Parameters:

make_framefunction

New frame creator function for the clip.

with_memoize(memoize)

Sets whether the clip should keep the last frame read in memory.

Parameters:

memoizebool

Indicates if the clip should keep the last frame read in memory.

with_start(t, change_end=True)

Returns a copy of the clip, with the start attribute set to t, which can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’.

These changes are also applied to the audio and mask clips of the current clip, if they exist.

Parameters:

tfloat or tuple or str

New start attribute value for the clip.

change_endbool optional

Indicates if the end attribute value must be changed accordingly, if possible. If change_end=True and the clip has a duration attribute, the end attribute of the clip will be updated to start + duration. If change_end=False and the clip has a end attribute, the duration attribute of the clip will be updated to end - start.

write_audiofile(filename, fps=None, nbytes=2, buffersize=2000, codec=None, bitrate=None, ffmpeg_params=None, write_logfile=False, logger='bar')

Writes an audio file from the AudioClip.

Parameters:

filename

Name of the output file, as a string or a path-like object.

fps

Frames per second. If not set, it will try default to self.fps if already set, otherwise it will default to 44100.

nbytes

Sample width (set to 2 for 16-bit sound, 4 for 32-bit sound)

codec

Which audio codec should be used. If None provided, the codec is determined based on the extension of the filename. Choose ‘pcm_s16le’ for 16-bit wav and ‘pcm_s32le’ for 32-bit wav.

bitrate

Audio bitrate, given as a string like ‘50k’, ‘500k’, ‘3000k’. Will determine the size and quality of the output file. Note that it mainly an indicative goal, the bitrate won’t necessarily be the this in the output file.

ffmpeg_params

Any additional parameters you would like to pass, as a list of terms, like [‘-option1’, ‘value1’, ‘-option2’, ‘value2’]

write_logfile

If true, produces a detailed logfile named filename + ‘.log’ when writing the file

logger

Either "bar" for progress bar or None or any Proglog logger.

CompositeAudioClip

class moviepy.audio.AudioClip.CompositeAudioClip(clips)

Bases: moviepy.audio.AudioClip.AudioClip

Clip made by composing several AudioClips.

An audio clip made by putting together several audio clips.

Parameters:

clips

List of audio clips, which may start playing at different times or together, depends on their start attributes. If all have their duration attribute set, the duration of the composite clip is computed automatically.

audio_delay(offset=0.2, n_repeats=8, decay=1)

Repeats audio certain number of times at constant intervals multiplying their volume levels using a linear space in the range 1 to decay argument value.

Parameters:

offsetfloat, optional

Gap between repetitions start times, in seconds.

n_repeatsint, optional

Number of repetitions (without including the clip itself).

decayfloat, optional

Multiplication factor for the volume level of the last repetition. Each repetition will have a value in the linear function between 1 and this value, increasing or decreasing constantly. Keep in mind that the last repetition will be muted if this is 0, and if is greater than 1, the volume will increase for each repetition.

Examples

>>> from moviepy import *
>>> videoclip = AudioFileClip('myaudio.wav').fx(
...     audio_delay, offset=.2, n_repeats=10, decayment=.2
... )

>>> # stereo A note
>>> make_frame = lambda t: np.array(
...     [np.sin(440 * 2 * np.pi * t), np.sin(880 * 2 * np.pi * t)]
... ).T
... clip = AudioClip(make_frame=make_frame, duration=0.1, fps=44100)
... clip = audio_delay(clip, offset=.2, n_repeats=11, decay=0)

audio_fadein(duration)

Return an audio (or video) clip that is first mute, then the sound arrives progressively over duration seconds.

Parameters:

durationfloat

How long does it take for the sound to return to its normal level.

Examples

>>> clip = VideoFileClip("media/chaplin.mp4")
>>> clip.fx(audio_fadein, "00:00:06")

audio_fadeout(duration)

Return a sound clip where the sound fades out progressively over duration seconds at the end of the clip.

Parameters:

durationfloat

How long does it take for the sound to reach the zero level at the end of the clip.

Examples

>>> clip = VideoFileClip("media/chaplin.mp4")
>>> clip.fx(audio_fadeout, "00:00:06")

audio_loop(n_loops=None, duration=None)

Loops over an audio clip.

Returns an audio clip that plays the given clip either n_loops times, or during duration seconds.

Examples

>>> from moviepy import *
>>> videoclip = VideoFileClip('myvideo.mp4')
>>> music = AudioFileClip('music.ogg')
>>> audio = afx.audio_loop( music, duration=videoclip.duration)
>>> videoclip.with_audio(audio)

audio_normalize()

Return a clip whose volume is normalized to 0db.

Return an audio (or video) clip whose audio volume is normalized so that the maximum volume is at 0db, the maximum achievable volume.

Examples

>>> from moviepy import *
>>> videoclip = VideoFileClip('myvideo.mp4').fx(afx.audio_normalize)

close()

Release any resources that are in use.

copy()

Allows the usage of .copy() in clips as chained methods invocation.

cutout(start_time, end_time)

Returns a clip playing the content of the current clip but skips the extract between start_time and end_time, which can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’.

If the original clip has a duration attribute set, the duration of the returned clip is automatically computed as `` duration - (end_time - start_time)``.

The resulting clip’s audio and mask will also be cutout if they exist.

Parameters:

start_timefloat or tuple or str

Moment from which frames will be ignored in the resulting output.

end_timefloat or tuple or str

Moment until which frames will be ignored in the resulting output.

property ends

Returns ending times for all clips in the composition.

fx(func, *args, **kwargs)

Returns the result of func(self, *args, **kwargs), for instance

>>> new_clip = clip.fx(resize, 0.2, method="bilinear")

is equivalent to

>>> new_clip = resize(clip, 0.2, method="bilinear")

The motivation of fx is to keep the name of the effect near its parameters when the effects are chained:

>>> from moviepy.video.fx import multiply_volume, resize, mirrorx
>>> clip.fx(multiply_volume, 0.5).fx(resize, 0.3).fx(mirrorx)
>>> # Is equivalent, but clearer than
>>> mirrorx(resize(multiply_volume(clip, 0.5), 0.3))

get_frame(t)

Gets a numpy array representing the RGB picture of the clip, or (mono or stereo) value for a sound clip, at time t.

Parameters:

tfloat or tuple or str

Moment of the clip whose frame will be returned.

is_playing(t)

If t is a time, returns true if t is between the start and the end of the clip. t can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’. If t is a numpy array, returns False if none of the t is in the clip, else returns a vector [b_1, b_2, b_3…] where b_i is true if tti is in the clip.

iter_chunks(chunksize=None, chunk_duration=None, fps=None, quantize=False, nbytes=2, logger=None)

Iterator that returns the whole sound array of the clip by chunks

iter_frames(fps=None, with_times=False, logger=None, dtype=None)

Iterates over all the frames of the clip.

Returns each frame of the clip as a HxWxN Numpy array, where N=1 for mask clips and N=3 for RGB clips.

This function is not really meant for video editing. It provides an easy way to do frame-by-frame treatment of a video, for fields like science, computer vision…

Parameters:

fpsint, optional

Frames per second for clip iteration. Is optional if the clip already has a fps attribute.

with_timesbool, optional

Ff True yield tuples of (t, frame) where t is the current time for the frame, otherwise only a frame object.

loggerstr, optional

Either "bar" for progress bar or None or any Proglog logger.

dtypetype, optional

Type to cast Numpy array frames. Use dtype="uint8" when using the pictures to write video, images…

Examples

>>> # prints the maximum of red that is contained
>>> # on the first line of each frame of the clip.
>>> from moviepy import VideoFileClip
>>> myclip = VideoFileClip('myvideo.mp4')
>>> print ( [frame[0,:,0].max()
             for frame in myclip.iter_frames()])

loop(n=None, duration=None)

Returns a clip that plays the current clip in an infinite loop. Ideal for clips coming from GIFs.

Parameters:

n

Number of times the clip should be played. If None the the clip will loop indefinitely (i.e. with no set duration).

duration

Total duration of the clip. Can be specified instead of n.

make_frame(t)

Renders a frame for the composition for the time t.

max_volume(stereo=False, chunksize=50000, logger=None)

Returns the maximum volume level of the clip.

multiply_stereo_volume(left=1, right=1)

For a stereo audioclip, this function enables to change the volume of the left and right channel separately (with the factors left and right). Makes a stereo audio clip in which the volume of left and right is controllable.

Examples

>>> from moviepy import AudioFileClip
>>> music = AudioFileClip('music.ogg')
>>> audio_r = music.multiply_stereo_volume(left=0, right=1)  # mute left channel/s
>>> audio_h = music.multiply_stereo_volume(left=0.5, right=0.5)  # half audio

multiply_volume(factor, start_time=None, end_time=None)

Returns a clip with audio volume multiplied by the value factor. Can be applied to both audio and video clips.

Parameters:

factorfloat

Volume multiplication factor.

start_timefloat, optional

Time from the beginning of the clip until the volume transformation begins to take effect, in seconds. By default at the beginning.

end_timefloat, optional

Time from the beginning of the clip until the volume transformation ends to take effect, in seconds. By default at the end.

Examples

>>> from moviepy import AudioFileClip
>>>
>>> music = AudioFileClip('music.ogg')
>>> doubled_audio_clip = clip.multiply_volume(2)  # doubles audio volume
>>> half_audio_clip = clip.multiply_volume(0.5)  # half audio
>>>
>>> # silenced clip during one second at third
>>> silenced_clip = clip.multiply_volume(0, start_time=2, end_time=3)

preview(*args, **kwargs)

NOT AVAILABLE: clip.preview requires importing from moviepy.editor

property starts

Returns starting times for all clips in the composition.

subclip(start_time=0, end_time=None)

Returns a clip playing the content of the current clip between times start_time and end_time, which can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’.

The mask and audio of the resulting subclip will be subclips of mask and audio the original clip, if they exist.

Parameters:

start_timefloat or tuple or str, optional

Moment that will be chosen as the beginning of the produced clip. If is negative, it is reset to clip.duration + start_time.

end_timefloat or tuple or str, optional

Moment that will be chosen as the end of the produced clip. If not provided, it is assumed to be the duration of the clip (potentially infinite). If is negative, it is reset to clip.duration + end_time. For instance:

>>> # cut the last two seconds of the clip:
>>> new_clip = clip.subclip(0, -2)

If end_time is provided or if the clip has a duration attribute, the duration of the returned clip is set automatically.

time_transform(time_func, apply_to=None, keep_duration=False)

Returns a Clip instance playing the content of the current clip but with a modified timeline, time t being replaced by another time time_func(t).

Parameters:

time_funcfunction

A function t -> new_t.

apply_to{“mask”, “audio”, [“mask”, “audio”]}, optional

Can be either ‘mask’, or ‘audio’, or [‘mask’,’audio’]. Specifies if the filter transform should also be applied to the audio or the mask of the clip, if any.

keep_durationbool, optional

False (default) if the transformation modifies the duration of the clip.

Examples

>>> # plays the clip (and its mask and sound) twice faster
>>> new_clip = clip.time_transform(lambda t: 2*t, apply_to=['mask', 'audio'])
>>>
>>> # plays the clip starting at t=3, and backwards:
>>> new_clip = clip.time_transform(lambda t: 3-t)

to_soundarray(tt=None, fps=None, quantize=False, nbytes=2, buffersize=50000)

Transforms the sound into an array that can be played by pygame or written in a wav file. See AudioClip.preview.

Parameters:

fps

Frame rate of the sound for the conversion. 44100 for top quality.

nbytes

Number of bytes to encode the sound: 1 for 8bit sound, 2 for 16bit, 4 for 32bit sound.

transform(func, apply_to=None, keep_duration=True)

General processing of a clip.

Returns a new Clip whose frames are a transformation (through function func) of the frames of the current clip.

Parameters:

funcfunction

A function with signature (gf,t -> frame) where gf will represent the current clip’s get_frame method, i.e. gf is a function (t->image). Parameter t is a time in seconds, frame is a picture (=Numpy array) which will be returned by the transformed clip (see examples below).

apply_to{“mask”, “audio”, [“mask”, “audio”]}, optional

Can be either 'mask', or 'audio', or ['mask','audio']. Specifies if the filter should also be applied to the audio or the mask of the clip, if any.

keep_durationbool, optional

Set to True if the transformation does not change the duration of the clip.

Examples

In the following new_clip a 100 pixels-high clip whose video content scrolls from the top to the bottom of the frames of clip at 50 pixels per second.

>>> filter = lambda get_frame,t : get_frame(t)[int(t):int(t)+50, :]
>>> new_clip = clip.transform(filter, apply_to='mask')

with_duration(duration, change_end=True)

Returns a copy of the clip, with the duration attribute set to t, which can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’. Also sets the duration of the mask and audio, if any, of the returned clip.

If change_end is False, the start attribute of the clip will be modified in function of the duration and the preset end of the clip.

Parameters:

durationfloat

New duration attribute value for the clip.

change_endbool, optional

If True, the end attribute value of the clip will be adjusted accordingly to the new duration using clip.start + duration.

with_end(t)

Returns a copy of the clip, with the end attribute set to t, which can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’. Also sets the duration of the mask and audio, if any, of the returned clip.

Parameters:

tfloat or tuple or str

New end attribute value for the clip.

with_fps(fps, change_duration=False)

Returns a copy of the clip with a new default fps for functions like write_videofile, iterframe, etc.

Parameters:

fpsint

New fps attribute value for the clip.

change_durationbool, optional

If change_duration=True, then the video speed will change to match the new fps (conserving all frames 1:1). For example, if the fps is halved in this mode, the duration will be doubled.

with_is_mask(is_mask)

Says whether the clip is a mask or not.

Parameters:

is_maskbool

New is_mask attribute value for the clip.

with_make_frame(make_frame)

Sets a make_frame attribute for the clip. Useful for setting arbitrary/complicated videoclips.

Parameters:

make_framefunction

New frame creator function for the clip.

with_memoize(memoize)

Sets whether the clip should keep the last frame read in memory.

Parameters:

memoizebool

Indicates if the clip should keep the last frame read in memory.

with_start(t, change_end=True)

Returns a copy of the clip, with the start attribute set to t, which can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’.

These changes are also applied to the audio and mask clips of the current clip, if they exist.

Parameters:

tfloat or tuple or str

New start attribute value for the clip.

change_endbool optional

Indicates if the end attribute value must be changed accordingly, if possible. If change_end=True and the clip has a duration attribute, the end attribute of the clip will be updated to start + duration. If change_end=False and the clip has a end attribute, the duration attribute of the clip will be updated to end - start.

write_audiofile(filename, fps=None, nbytes=2, buffersize=2000, codec=None, bitrate=None, ffmpeg_params=None, write_logfile=False, logger='bar')

Writes an audio file from the AudioClip.

Parameters:

filename

Name of the output file, as a string or a path-like object.

fps

Frames per second. If not set, it will try default to self.fps if already set, otherwise it will default to 44100.

nbytes

Sample width (set to 2 for 16-bit sound, 4 for 32-bit sound)

codec

Which audio codec should be used. If None provided, the codec is determined based on the extension of the filename. Choose ‘pcm_s16le’ for 16-bit wav and ‘pcm_s32le’ for 32-bit wav.

bitrate

Audio bitrate, given as a string like ‘50k’, ‘500k’, ‘3000k’. Will determine the size and quality of the output file. Note that it mainly an indicative goal, the bitrate won’t necessarily be the this in the output file.

ffmpeg_params

Any additional parameters you would like to pass, as a list of terms, like [‘-option1’, ‘value1’, ‘-option2’, ‘value2’]

write_logfile

If true, produces a detailed logfile named filename + ‘.log’ when writing the file

logger

Either "bar" for progress bar or None or any Proglog logger.