mpcompress.utils.stream_helper

NalType

Network Abstraction Layer (NAL) unit types.

Attributes:

Name	Type	Description
`NAL_SPS`	`int`	Sequence Parameter Set type (0).
`NAL_I`	`int`	Intra-coded frame type (1).
`NAL_P`	`int`	Predictive-coded frame type (2).

SpsManager

SpsManager()

Manager for Sequence Parameter Sets (SPS).

Maintains a list of SPS entries and provides methods to find, reuse, update, and insert SPS configurations.

find_identical_sps

find_identical_sps(target_sps)

Find an SPS with identical parameters to the target.

Parameters:

Name	Type	Description	Default
`target_sps`	`dict`	SPS dictionary to match against.	required

Returns:

Name	Type	Description
`sps`	`dict or None`	A copy of the matching SPS if found, None otherwise.

find_sps_by_id

find_sps_by_id(sps_id)

Find an SPS by its ID.

Parameters:

Name	Type	Description	Default
`sps_id`	`int`	The SPS ID to search for.	required

Returns:

Name	Type	Description
`sps`	`dict or None`	The SPS dictionary if found, None otherwise.

resue_or_insert

resue_or_insert(sps)

Reuse an identical SPS if found, otherwise insert a new one.

If an identical SPS exists (based on height, width, use_ada_i, ec_part), returns the existing SPS. Otherwise, assigns a new sps_id and inserts it.

Parameters:

Name	Type	Description	Default
`sps`	`dict`	SPS dictionary to reuse or insert.	required

Returns:

Name	Type	Description
`sps`	`dict`	The SPS dictionary (existing or new).
`inserted`	`bool`	True if a new SPS was inserted, False if reused.

update_or_insert

update_or_insert(sps)

Update an existing SPS or insert a new one.

If an SPS with the same sps_id exists, it is updated. Otherwise, a new SPS is appended to the list.

Parameters:

Name	Type	Description	Default
`sps`	`dict`	SPS dictionary to update or insert.	required

filesize

filesize(filepath: str) -> int

Get the size of a file in bytes.

Parameters:

Name	Type	Description	Default
`filepath`	`str`	Path to the file.	required

Returns:

Name	Type	Description
`size`	`int`	File size in bytes.

Raises:

Type	Description
`ValueError`	If the file does not exist or is not a regular file.

read_bytes

read_bytes(fd, n, fmt='>{:d}s')

Read bytes from a file descriptor.

Parameters:

Name	Type	Description	Default
`fd`	`file`	File descriptor to read from.	required
`n`	`int`	Number of bytes to read.	required
`fmt`	`str`	Format string for struct.unpack. Defaults to ">{:d}s" (big-endian).	`'>{:d}s'`

Returns:

Name	Type	Description
`out_bytes`	`bytes`	The read bytes.

read_picture_remaining

read_picture_remaining(fd)

Read the remaining picture fields from a file descriptor.

Reads quantization parameter, bitstream length, and bitstream data after the initial header (nal_type, sps_id) has been read.

Parameters:

Name	Type	Description	Default
`fd`	`file`	File descriptor to read from.	required

Returns:

Name	Type	Description
`qp`	`int`	Quantization parameter (0-255)
`bit_stream`	`bytes`	The encoded bitstream data

read_sps_remaining

read_sps_remaining(fd, sps_id)

Read the remaining SPS fields from a file descriptor.

Reads height, width, and flags (ec_part, use_ada_i) after the initial header has been read. The sps_id is provided as a parameter.

Parameters:

Name	Type	Description	Default
`fd`	`file`	File descriptor to read from.	required
`sps_id`	`int`	The SPS ID (already read from header).	required

Returns:

Name	Type	Description
`sps`	`dict`	SPS dictionary containing the sps_id, height, width, ec_part, and use_ada_i.

read_uchars

read_uchars(fd, n, fmt='>{:d}B')

Read unsigned characters (bytes) from a file descriptor.

Parameters:

Name	Type	Description	Default
`fd`	`file`	File descriptor to read from.	required
`n`	`int`	Number of unsigned characters to read.	required
`fmt`	`str`	Format string for struct.unpack. Defaults to ">{:d}B" (big-endian).	`'>{:d}B'`

Returns:

Name	Type	Description
`out_chars`	`tuple`	Tuple of n unsigned characters (0-255).

read_uint_adaptive

read_uint_adaptive(f)

Read an unsigned integer using adaptive-length decoding.

Decodes integers written by write_uint_adaptive. The encoding uses variable-length representation based on the value size.

Parameters:

Name	Type	Description	Default
`f`	`file`	File descriptor to read from.	required

Returns:

Name	Type	Description
`out_value`	`int`	The decoded unsigned integer.

read_uints

read_uints(fd, n, fmt='>{:d}I')

Read unsigned integers from a file descriptor.

Parameters:

Name	Type	Description	Default
`fd`	`file`	File descriptor to read from.	required
`n`	`int`	Number of unsigned integers to read.	required
`fmt`	`str`	Format string for struct.unpack. Defaults to ">{:d}I" (big-endian).	`'>{:d}I'`

Returns:

Name	Type	Description
`out_uints`	`tuple`	Tuple of n unsigned integers.

read_ushorts

read_ushorts(fd, n, fmt='>{:d}H')

Read unsigned short integers (16-bit) from a file descriptor.

Parameters:

Name	Type	Description	Default
`fd`	`file`	File descriptor to read from.	required
`n`	`int`	Number of unsigned shorts to read.	required
`fmt`	`str`	Format string for struct.unpack. Defaults to ">{:d}H" (big-endian).	`'>{:d}H'`

Returns:

Name	Type	Description
`out_ushorts`	`tuple`	Tuple of n unsigned short integers.

read_vps

read_vps(fd)

Read a Video Parameter Set (VPS) header from a file descriptor.

For NAL types < 3, reads a simple header with nal_type and sps_id. For other NAL types, reads frame_num and associated sps_ids.

Parameters:

Name	Type	Description	Default
`fd`	`file`	File descriptor to read from.	required

Returns:

Name	Type	Description
`header`	`dict`	Dictionary containing the nal_type, sps_id, frame_num, and sps_ids.

write_bytes

write_bytes(fd, values, fmt='>{:d}s')

Write bytes to a file descriptor.

Parameters:

Name	Type	Description	Default
`fd`	`file`	File descriptor to write to.	required
`values`	`bytes`	Bytes to write.	required
`fmt`	`str`	Format string for struct.pack. Defaults to ">{:d}s" (big-endian).	`'>{:d}s'`

Returns:

Name	Type	Description
`bytes_written`	`int`	Number of bytes written, or 0 if values is empty.

write_picture

write_picture(fd, is_i_frame, sps_id, qp, bit_stream)

Write a picture (frame) to a file descriptor.

Format

nal_type(4 bits), sps_id(4 bits) - 1 byte
qp (quantization parameter) - 1 byte
bit_stream length (variable length)
bit_stream data

Note: Since all streams are written to the same file, the per-frame length must be written. If frames were packed independently, this would not be necessary.

Parameters:

Name	Type	Description	Default
`fd`	`file`	File descriptor to write to.	required
`is_i_frame`	`bool`	True if this is an I-frame, False for P-frame.	required
`sps_id`	`int`	SPS ID (0-15).	required
`qp`	`int`	Quantization parameter (0-255).	required
`bit_stream`	`bytes`	The encoded bitstream data for this frame.	required

Returns:

Name	Type	Description
`bytes_written`	`int`	Number of bytes written.

Raises:

Type	Description
`AssertionError`	If qp is not in [0, 256).

write_picture_pps

write_picture_pps(fd, pps, bit_stream)

Write a picture using Picture Parameter Set (PPS) information.

Similar to write_picture, but uses a PPS dictionary that already contains nal_type and sps_id.

Parameters:

Name	Type	Description	Default
`fd`	`file`	File descriptor to write to.	required
`pps`	`dict`	PPS dictionary containing the nal_type, sps_id, and qp.	required
`bit_stream`	`bytes`	The encoded bitstream data for this frame.	required

Returns:

Name	Type	Description
`bytes_written`	`int`	Number of bytes written.

write_sps

write_sps(fd, sps)

Write a Sequence Parameter Set (SPS) to a file descriptor.

Format

nal_type(4 bits), sps_id(4 bits) - 1 byte
height (variable length)
width (variable length)
reserved(6 bits), ec_part(1 bit), use_ada_i(1 bit) - 1 byte

Parameters:

Name	Type	Description	Default
`fd`	`file`	File descriptor to write to.	required
`sps`	`dict`	SPS dictionary containing: - sps_id (int): SPS ID (0-15) - height (int): Frame height - width (int): Frame width - ec_part (int): EC partition flag (0-1) - use_ada_i (int): Adaptive I-frame flag (0-1)	required

Returns:

Name	Type	Description
`bytes_written`	`int`	Number of bytes written.

Raises:

Type	Description
`AssertionError`	If sps_id is not in [0, 16) or use_ada_i is not in [0, 2).

write_uchars

write_uchars(fd, values, fmt='>{:d}B')

Write unsigned characters (bytes) to a file descriptor.

Parameters:

Name	Type	Description	Default
`fd`	`file`	File descriptor to write to.	required
`values`	`list`	Sequence of unsigned characters (0-255) to write.	required
`fmt`	`str`	Format string for struct.pack. Defaults to ">{:d}B" (big-endian).	`'>{:d}B'`

Returns:

Name	Type	Description
`bytes_written`	`int`	Number of bytes written (1 byte per character).

write_uint_adaptive

write_uint_adaptive(f, a)

Write an unsigned integer using adaptive-length encoding.

The encoding uses variable-length representation: - 1 byte for values < 128 (7 bits) - 2 bytes for values < 16384 (14 bits) - 4 bytes for values < 1073741824 (30 bits)

Parameters:

Name	Type	Description	Default
`f`	`file`	File descriptor to write to.	required
`a`	`int`	Unsigned integer to write (must be < 2^30).	required

Returns:

Name	Type	Description
`bytes_written`	`int`	Number of bytes written (1, 2, or 4).

write_uints

write_uints(fd, values, fmt='>{:d}I')

Write unsigned integers to a file descriptor.

Parameters:

Name	Type	Description	Default
`fd`	`file`	File descriptor to write to.	required
`values`	`list`	Sequence of unsigned integers to write.	required
`fmt`	`str`	Format string for struct.pack. Defaults to ">{:d}I" (big-endian).	`'>{:d}I'`

Returns:

Name	Type	Description
`bytes_written`	`int`	Number of bytes written (4 bytes per integer).

write_ushorts

write_ushorts(fd, values, fmt='>{:d}H')

Write unsigned short integers (16-bit) to a file descriptor.

Parameters:

Name	Type	Description	Default
`fd`	`file`	File descriptor to write to.	required
`values`	`list`	Sequence of unsigned short integers to write.	required
`fmt`	`str`	Format string for struct.pack. Defaults to ">{:d}H" (big-endian).	`'>{:d}H'`

Returns:

Name	Type	Description
`bytes_written`	`int`	Number of bytes written (2 bytes per short).