Videos

bewegung.Video objects define and structure animations. They hold information on the width, height, frames per second and length of the video. Once a bewegung.Video object has been created, it exposes decorator methods for user-defined sequence classes, prepare task methods and layer task methods. After the decoration of all relevant user-defined classes and methods, a video can be rendered by calling bewegung.Video.render(). Alternatively, individual frames can be extracted as still-images by calling bewegung.Video.render_frame(). In the latter case, a bewegung.Video object must be reset at least once in advance by calling bewegung.Video.reset(). The rendering of videos is fully parallelized. bewegung.Video objects can use different encoders for generating the actual video file.

bewegung.Video objects provide access to different canvas types and backends, see bewegung.Video.canvas(). bewegung.Video objects can, if required, manage a context dictionary for user-defined information, see bewegung.Video.ctx, which is exposed to all sequences, prepare tasks and layer tasks. bewegung.Video objects also manage two bewegung.IndexPool objects - one for prepare tasks, see bewegung.Video.preporder, and one for layer tasks, see bewegung.Video.z-index.

The Video Class

class bewegung.Video(width, height, ctx=None, fps=60, seconds=None, frames=None)

This class is the “core” of bewegung. It generates video objects. They manage sequences, layer tasks and prepare tasks Video objects are also responsible for rendering actual video files and individual frames.

Video objects are mutable.

Parameters
  • width (int) – Video width in pixels

  • height (int) – Video width in pixels

  • ctx (Optional[Dict]) – Context, store for any type of video context data

  • fps (int) – Frames per second

  • seconds (Union[float, int, None]) – Duration of video in seconds (frames and seconds are mutually exclusive. Specify excactly one of two.)

  • frames (Optional[int]) – Duration of video as number of frames (frames and seconds are mutually exclusive. Specify excactly one of two.)

__len__()

Duration of video as number of frames

Return type

int

__repr__()

String representation for interactive use

Return type

str

canvas(backend='drawingboard', **kwargs)

A method to create function pointers to factory functions generating new canvases. The pointers can be passed to the canvas parameter in the bewegung.Video.layer() decorator method.

Parameters
  • backend (str) – Selected type of canvas, i.e. name of desired backend.

  • kwargs – Keyword arguments of the selected backend’s canvas creation function.

Return type

Callable

property ctx: Dict

Context (mutable), store for any type of video context data

Return type

Dict

property fps: int

Frames per second

Return type

int

property height: int

Height of video in pixels

Return type

int

layer(zindex=None, canvas=None, offset=None)

A decorator for decorating layer methods (tasks) within sequence classes. Methods are wrapped with callable bewegung.core.layer.Layer objects.

Parameters
  • zindex (Optional[int]) – A number, managed by an bewegung.IndexPool object (bewegung.Video.zindex), representing the relative position within a stack of layer tasks. If not provided, the new layer will be created on top.

  • canvas (Optional[Callable]) – A function pointer to a factory function, generating a new canvas once per frame for the layer task. The pointer is typically generated by the bewegung.Video.canvas() method.

  • offset (Optional[Vector2D]) – The layer’s offset relative to the top-left corner of the video. The y-axis is downwards positive.

Return type

Callable

property length: bewegung.animation._abc.TimeABC

Duration of video

Return type

TimeABC

prepare(preporder=None)

A decorator for decorating prepare methods (tasks) within sequence classes.

Parameters

preporder (Optional[int]) – A number, managed by an bewegung.IndexPool object (bewegung.Video.preporder), representing the relative position within a set of prepare tasks. If not provided, the new task will be created at the end of the set.

Return type

Callable

property preporder: bewegung.animation._indexpool.IndexPool

Prepare-order bewegung.IndexPool object for prepare tasks (mutable)

Return type

IndexPool

render(processes=1, batchsize=256, encoder=None, frame_fn=None, video_fn=None)

A method for rendering the actual video file.

This function starts at least one Python sub-process (worker process) for rendering frames. Based on multiple worker processes, multiple frames can be rendered in parallel. If a filename for a video is specified, the rendered frames are streamed to a video encoder.

Parameters
  • processes (int) – Number of parallel frame rendering (worker) processes

  • batchsize (int) – Maximum number of frames rendered by a worker process before the (old) worker is replaced by a new worker. This option helps to prevent long rendering jobs from running out of memory.

  • encoder (Optional[EncoderABC]) – A video encoder object. If omitted, a bewegung.FFmpegH264Encoder object will generated and used.

  • frame_fn (Optional[str]) – A Python string (representing a path) including an integer replacement field called index. If specified, individual frames will be stored here. If omitted, no frames will be stored.

  • video_fn (Optional[str]) – Location and name (path) of where to store the video file. If omitted, no video will be rendered. However, indivual frames may in fact still be rendered if frame_fn has been specified.

render_frame(time, return_frame=True, frame_fn=None)

A method for rendering individual frames of the video.

The frames can optionally be written to disk and/or returned to the caller. Before calling this method for the first time, bewegung.Video.reset() must be invoked!

Parameters
  • time (Time) – Time of the frame relative to the beginning of the video

  • return_frame (bool) – If True, the frame is returned to the caller of the method.

  • frame_fn (Optional[str]) – Location and name (path) of where to store the rendered frame. If omitted, the frame is not stored.

Return type

Optional[Image]

Returns

If requested via return_frame, a pillow image object is returned.

reset()

This method allows to reset a video object in preparation of a new render run. It is automatically invoked when calling bewegung.Video.render(). It may instead be used before rendering indivual frames with bewegung.Video.render_frame().

sequence(start=None, stop=None, length=None)

A decorator for decorating user-defined sequence classes. New classes are created by making bewegung.core.sequence.Sequence inherit from the user-defined sequence classes.

Parameters
  • start (Optional[Time]) – Time of start of sequence within the video. A negative time can be used to specify a time relative to the end of the video. Defaults to the beginning of the video.

  • stop (Optional[Time]) – Time of stop of sequence within the video. A negative time can be used to specify a time relative to the end of the video. Defaults to the end of the video. stop and length are mutually exclusive. Specify one at most.

  • length (Optional[Time]) – Length of the sequence. stop and length are mutually exclusive. Specify one at most.

Return type

Callable

time(index)

Generates a new bewegung.Time object from a given number of frames based on the video’s frames per second.

Parameters

index (int) – Number of frames

Return type

TimeABC

time_from_seconds(seconds)

Generates a new bewegung.Time object from a given time in seconds based on the video’s frames per second.

Parameters

seconds (Union[float, int]) – Time in seconds

Return type

TimeABC

property width: int

Width of video in pixels

Return type

int

property zindex: bewegung.animation._indexpool.IndexPool

Z-index bewegung.IndexPool object for layers (mutable)

Return type

IndexPool