Skip to content

avblocks/avblocks-py

Repository files navigation

avblocks-py (beta)

AVBlocks Python SDK

Usage

Getting Started

Library Initialization

Before using any AVBlocks functionality, initialize the library:

from avblocks import Library Library.initialize() # Set license information. AVBlocks runs in demo mode if license is not set.  # Library.set_license("<license-string>") # Your code here Library.shutdown()

Core Concepts

MediaSocket

A MediaSocket represents an input or output media endpoint. It describes:

  • The media file location (file property)
  • The stream type (stream_type property)
  • One or more media pins (pins collection)
from avblocks import MediaSocket, StreamType socket = MediaSocket() socket.file = "input.mp4" socket.stream_type = StreamType.UncompressedVideo

MediaPin

A MediaPin represents a single media stream (audio or video) within a MediaSocket. Each pin contains:

  • Stream information (stream_info property) - describes the format and characteristics of the stream
  • Stream configuration for encoding/decoding

Key Properties:

  • stream_info - Contains detailed format information (VideoStreamInfo or AudioStreamInfo)

Example for video input:

from avblocks import MediaPin, VideoStreamInfo, StreamType, ColorFormat, ScanType pin = MediaPin() vsi = VideoStreamInfo() pin.stream_info = vsi vsi.stream_type = StreamType.UncompressedVideo vsi.frame_width = 176 vsi.frame_height = 144 vsi.color_format = ColorFormat.YUV420 vsi.frame_rate = 30.0 vsi.scan_type = ScanType.Progressive socket.pins.add(pin)

MediaInfo

MediaInfo is used to extract metadata and stream information from media files without processing the content.

Key Features:

  • Extract audio/video stream details
  • Read file metadata (title, artist, album, etc.)
  • No transcoding required
from avblocks import MediaInfo info = MediaInfo() info.inputs[0].file = "input.mp4" if info.open(): # Access stream information for pin in info.outputs[0].pins: stream_info = pin.stream_info # Process stream info # Access metadata for attr in info.outputs[0].metadata: print(f"{attr.name}: {attr.value}") info.close() else: # Handle error error = info.error

Common Operations

Media Information Extraction

Stream Information

from avblocks import MediaInfo, MediaType info = MediaInfo() info.inputs[0].file = input_file if info.open(): for pin in info.outputs[0].pins: si = pin.stream_info if si.media_type == MediaType.Video: vsi = si # VideoStreamInfo print(f"Video: {vsi.frame_width}x{vsi.frame_height}") print(f" Frame Rate: {vsi.frame_rate}") print(f" Color Format: {vsi.color_format}") elif si.media_type == MediaType.Audio: asi = si # AudioStreamInfo print(f"Audio: {asi.sample_rate}Hz, {asi.channels} channels") print(f" Bits Per Sample: {asi.bits_per_sample}") info.close()

Metadata Extraction

from avblocks import MediaInfo info = MediaInfo() info.inputs[0].file = input_file if info.open(): for attr in info.outputs[0].metadata: print(f"{attr.name}: {attr.value}") info.close()

Video Encoding

Encode Raw YUV to H.264/AVC

from avblocks import (MediaSocket, MediaPin, VideoStreamInfo, Transcoder, StreamType, ColorFormat, ScanType) # Create input socket for raw YUV in_vsi = VideoStreamInfo() in_vsi.stream_type = StreamType.UncompressedVideo in_vsi.scan_type = ScanType.Progressive in_vsi.frame_width = 176 in_vsi.frame_height = 144 in_vsi.color_format = ColorFormat.YUV420 in_vsi.frame_rate = 30.0 in_pin = MediaPin() in_pin.stream_info = in_vsi in_socket = MediaSocket() in_socket.stream_type = StreamType.UncompressedVideo in_socket.file = "input.yuv" in_socket.pins.add(in_pin) # Create output socket for H.264 out_vsi = VideoStreamInfo() out_vsi.stream_type = StreamType.H264 out_vsi.frame_width = 176 out_vsi.frame_height = 144 out_vsi.frame_rate = 30.0 out_pin = MediaPin() out_pin.stream_info = out_vsi out_socket = MediaSocket() out_socket.stream_type = StreamType.H264 out_socket.file = "output.h264" out_socket.pins.add(out_pin) # Encode transcoder = Transcoder() transcoder.inputs.add(in_socket) transcoder.outputs.add(out_socket) if transcoder.open(): if transcoder.run(): print("Encoding successful") transcoder.close()

Encode with Preset

from avblocks import MediaSocket, Transcoder, Preset in_socket = MediaSocket() in_socket.file = "input.yuv" # ... configure input out_socket = MediaSocket() out_socket.file = "output.mp4" out_socket.preset = Preset.Video.Generic.MP4.Base_H264_AAC transcoder = Transcoder() transcoder.inputs.add(in_socket) transcoder.outputs.add(out_socket) if transcoder.open(): transcoder.run() transcoder.close()

Video Decoding

Decode H.264 to Raw YUV

from avblocks import (MediaSocket, MediaPin, VideoStreamInfo, Transcoder, StreamType, ColorFormat) # Create input socket for H.264 in_socket = MediaSocket() in_socket.stream_type = StreamType.H264 in_socket.file = "input.h264" # Create output socket for raw YUV out_vsi = VideoStreamInfo() out_vsi.stream_type = StreamType.UncompressedVideo out_vsi.color_format = ColorFormat.YUV420 out_pin = MediaPin() out_pin.stream_info = out_vsi out_socket = MediaSocket() out_socket.stream_type = StreamType.UncompressedVideo out_socket.file = "output.yuv" out_socket.pins.add(out_pin) # Decode transcoder = Transcoder() transcoder.inputs.add(in_socket) transcoder.outputs.add(out_socket) if transcoder.open(): transcoder.run() transcoder.close()

Audio Encoding

Encode WAV to AAC (ADTS)

from avblocks import MediaSocket, Transcoder, StreamType, StreamSubType in_socket = MediaSocket() in_socket.file = "input.wav" out_socket = MediaSocket() out_socket.stream_type = StreamType.Aac out_socket.stream_sub_type = StreamSubType.AacAdts out_socket.file = "output.aac" transcoder = Transcoder() transcoder.inputs.add(in_socket) transcoder.outputs.add(out_socket) if transcoder.open(): transcoder.run() transcoder.close()

Encode WAV to MP3

from avblocks import MediaSocket, Transcoder, StreamType in_socket = MediaSocket() in_socket.file = "input.wav" out_socket = MediaSocket() out_socket.file = "output.mp3" out_socket.stream_type = StreamType.Mp3 transcoder = Transcoder() transcoder.inputs.add(in_socket) transcoder.outputs.add(out_socket) if transcoder.open(): transcoder.run() transcoder.close()

Container Operations

Demux MP4 File

from avblocks import MediaSocket, Transcoder, StreamType # Extract video and audio streams from MP4 # Input in_socket = MediaSocket() in_socket.file = "input.mp4" # Output for video stream video_out = MediaSocket() video_out.stream_type = StreamType.H264 video_out.file = "video.mp4" # Output for audio stream audio_out = MediaSocket() audio_out.file = "audio.mp4" audio_out.stream_type = StreamType.Aac transcoder = Transcoder() transcoder.inputs.add(in_socket) transcoder.outputs.add(video_out) transcoder.outputs.add(audio_out) if transcoder.open(): transcoder.run() transcoder.close()

Mux MP4 File

from avblocks import MediaSocket, Transcoder # Combine separate audio and video files into MP4 container # Video input video_in = MediaSocket() video_in.file = "video.h264.mp4" # Audio input audio_in = MediaSocket() audio_in.file = "audio.aac.mp4" # Combined output out_socket = MediaSocket() out_socket.file = "output.mp4" transcoder = Transcoder() transcoder.inputs.add(video_in) transcoder.inputs.add(audio_in) transcoder.outputs.add(out_socket) if transcoder.open(): transcoder.run() transcoder.close()

Error Handling

from avblocks import Transcoder, ErrorInfo def print_error(action: str, error: ErrorInfo): if error: print(f"Error: {action}") print(f" Facility: {error.facility}") print(f" Code: {error.code}") print(f" Message: {error.message}") print(f" Hint: {error.hint}") transcoder = Transcoder() transcoder.inputs.add(in_socket) transcoder.outputs.add(out_socket) if not transcoder.open(): print_error("Open Transcoder", transcoder.error) return False if not transcoder.run(): print_error("Run Transcoder", transcoder.error) transcoder.close() return False transcoder.close()

Available Samples

See samples/README.md for a complete list of working examples including:

  • Media Info: Extract stream information and metadata
  • Encoding: AAC, MP3, H.264/AVC, with presets
  • Decoding: H.264 to YUV
  • Container Operations: Demux/Mux MP4 files
  • Misc: Re-encoding, slideshow generation

Development

Setup

macOS

  1. Download Core and Assets on macOS
  2. Setup for macOS

Linux

  1. Download Core and Assets on Linux
  2. Setup for Linux

Windows

  1. Download Core and Assets on Windows
  2. Setup for Windows

Run

Create virtual environment

macOS:

source configure.sh

Linux:

source configure.sh

Windows:

. .\configure.ps1

Run Samples

See README in the samples subdirectory.

How to obtain Commercial License

See License Options for details.

We offer discounts for:

  • Competitive product
  • Startup
  • Educational institution
  • Open source project