Skip to content

Asynchronous API

Asynchronous wrappers enabling non-blocking execution inside asyncio event loops.

AsyncHeifContext

pylibheif.AsyncHeifContext 

AsyncHeifContext(ctx: Optional[HeifContext] = None, executor: Optional[Executor] = None)

Async wrapper for HeifContext with custom executor and async factory support.

__doc__ class-attribute 

__doc__ = 'Async wrapper for HeifContext with custom executor and async factory support.'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__module__ class-attribute 

__module__ = 'pylibheif._async'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__weakref__ property 

__weakref__

list of weak references to the object

has_sequence property 

has_sequence

Check if the context contains any image sequence tracks.

max_decoding_threads property 

max_decoding_threads

Maximum background threads used for parallel tile decoding.

add_compatible_brand 

add_compatible_brand(brand: str) -> None

Add a compatible brand to the HEIF container (4-character FourCC).

add_visual_sequence_track 

add_visual_sequence_track(width: int, height: int, track_type: Union[HeifTrackType, int] = ImageSequence, timescale: int = 1000) -> AsyncHeifTrack

Add a visual sequence track to the context for encoding.

add_visual_sequence_track_async 

add_visual_sequence_track_async(width: int, height: int, track_type: Union[HeifTrackType, int] = ImageSequence, timescale: int = 1000) -> AsyncHeifTrack

Asynchronously add a visual sequence track.

close 

close()

Close the context and release resources.

from_file classmethod 

from_file(filename: str, executor: Optional[Executor] = None) -> AsyncHeifContext

Async factory method to construct and read context from file.

from_memory classmethod 

from_memory(data: Union[bytes, bytearray, memoryview], executor: Optional[Executor] = None) -> AsyncHeifContext

Async factory method to construct and read context from memory bytes.

from_stream classmethod 

from_stream(stream: Any, executor: Optional[Executor] = None) -> AsyncHeifContext

Async factory method to construct and read context from a Python stream.

get_image_handle 

get_image_handle(id: int) -> AsyncHeifImageHandle

Get async wrapper for specific image ID.

get_image_handle_async 

get_image_handle_async(id: int) -> AsyncHeifImageHandle

Asynchronously get image handle for specific image ID.

get_max_decoding_threads 

get_max_decoding_threads() -> int

Asynchronously get maximum background threads used for parallel tile decoding.

get_number_of_sequence_tracks 

get_number_of_sequence_tracks() -> int

Get the number of sequence tracks.

get_primary_image_handle 

get_primary_image_handle() -> AsyncHeifImageHandle

Get async wrapper for primary image handle.

get_primary_image_handle_async 

get_primary_image_handle_async() -> AsyncHeifImageHandle

Asynchronously get primary image handle.

get_sequence_duration 

get_sequence_duration() -> int

Get the total sequence duration in ticks.

get_sequence_timescale 

get_sequence_timescale() -> int

Get the sequence timescale (ticks per second).

get_sequence_track_ids 

get_sequence_track_ids() -> List[int]

Get the list of sequence track IDs.

get_track 

get_track(track_id: int = 0) -> AsyncHeifTrack

Get a track wrapper (use track_id=0 for first visual track).

get_track_async 

get_track_async(track_id: int = 0) -> AsyncHeifTrack

Asynchronously get a track wrapper.

read_from_file 

read_from_file(filename: str) -> None

Asynchronously read from file.

read_from_memory 

read_from_memory(data: Union[bytes, bytearray, memoryview]) -> None

Asynchronously read from memory.

read_from_stream 

read_from_stream(stream: Any) -> None

Asynchronously read from a Python file-like stream object.

reset 

reset() -> None

Reset context and release buffer references.

set_major_brand 

set_major_brand(brand: str) -> None

Set the major brand of the HEIF container (4-character FourCC).

set_max_decoding_threads 

set_max_decoding_threads(max_threads: int) -> None

Asynchronously set maximum background threads for parallel tile decoding.

set_number_of_sequence_repetitions 

set_number_of_sequence_repetitions(repetitions: int) -> None

Set the repetition count for the sequence (0 = infinite).

set_primary_image 

set_primary_image(handle: Union[HeifImageHandle, AsyncHeifImageHandle]) -> None

Designate an image handle as the primary image of the context.

set_primary_image_async 

set_primary_image_async(handle: Union[HeifImageHandle, AsyncHeifImageHandle]) -> None

Asynchronously designate an image handle as the primary image of the context.

set_sequence_timescale 

set_sequence_timescale(timescale: int) -> None

Set the sequence timescale (ticks per second).

write_to_bytes 

write_to_bytes(copy: bool = True) -> Union[bytes, memoryview]

Asynchronously export context to Python bytes (copy=True) or zero-copy memoryview (copy=False).

write_to_file 

write_to_file(filename: str) -> None

Asynchronously write to file.

write_to_memoryview 

write_to_memoryview() -> memoryview

Asynchronously export context directly to a zero-copy Python memoryview.

write_to_stream 

write_to_stream(stream: Any) -> None

Asynchronously write to a Python file-like stream object.

AsyncHeifImageHandle

pylibheif.AsyncHeifImageHandle 

AsyncHeifImageHandle(handle: HeifImageHandle, executor: Optional[Executor] = None)

Async wrapper for HeifImageHandle.

__doc__ class-attribute 

__doc__ = 'Async wrapper for HeifImageHandle.'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__module__ class-attribute 

__module__ = 'pylibheif._async'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__weakref__ property 

__weakref__

list of weak references to the object

depth_map property 

depth_map

Asynchronous DepthMap domain entity, or None if no depth image exists.

gain_map property 

gain_map

Asynchronous GainMap domain entity, or None if no gain map exists.

portrait_matte property 

portrait_matte

Apple Portrait Matte (foreground segmentation alpha mask), or None.

decode 

decode(colorspace: HeifColorspace = RGB, chroma: HeifChroma = InterleavedRGB, options: Optional[HeifDecodingOptions] = None, num_threads: Optional[int] = None, target_colorspace: Optional[Union[str, bytes]] = None, intent: Union[RenderingIntent, int, str] = <RenderingIntent.PERCEPTUAL: 0>, bpc: bool = True, prefer_nclx: bool = False) -> HeifImage

Asynchronously decode the image with optional color space conversion.

AsyncHeifEncoder

pylibheif.AsyncHeifEncoder 

AsyncHeifEncoder(format_or_descriptor, preset: str = '', executor: Optional[Executor] = None)

Async wrapper for HeifEncoder.

__doc__ class-attribute 

__doc__ = 'Async wrapper for HeifEncoder.'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__module__ class-attribute 

__module__ = 'pylibheif._async'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__weakref__ property 

__weakref__

list of weak references to the object

encode_image 

encode_image(context: Union[HeifContext, AsyncHeifContext], image: HeifImage, preset: str = '', options: Optional[HeifEncodingOptions] = None) -> HeifImageHandle

Asynchronously encode image.

encode_thumbnail 

encode_thumbnail(context: Union[HeifContext, AsyncHeifContext], image: HeifImage, master_image: Union[HeifImageHandle, AsyncHeifImageHandle], bbox_size: int, options: Optional[HeifEncodingOptions] = None) -> Optional[HeifImageHandle]

Asynchronously encode thumbnail image.

AsyncHeifTrack

pylibheif.AsyncHeifTrack 

AsyncHeifTrack(track: HeifTrack, executor: Optional[Executor] = None)

Async wrapper for HeifTrack (timed image sequences/animations).

__doc__ class-attribute 

__doc__ = 'Async wrapper for HeifTrack (timed image sequences/animations).'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__module__ class-attribute 

__module__ = 'pylibheif._async'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__weakref__ property 

__weakref__

list of weak references to the object

decode_next_image 

decode_next_image(colorspace: HeifColorspace = RGB, chroma: HeifChroma = InterleavedRGB, options: Optional[HeifDecodingOptions] = None) -> Optional[HeifImage]

Decode next image frame in sequence. Returns None at end of sequence.

decode_next_image_async 

decode_next_image_async(colorspace: HeifColorspace = RGB, chroma: HeifChroma = InterleavedRGB, options: Optional[HeifDecodingOptions] = None) -> Optional[HeifImage]

Asynchronously decode next image frame in sequence.

encode_end_of_sequence 

encode_end_of_sequence(encoder: Union[HeifEncoder, AsyncHeifEncoder]) -> None

Finalize the sequence track encoding.

encode_end_of_sequence_async 

encode_end_of_sequence_async(encoder: Union[HeifEncoder, AsyncHeifEncoder]) -> None

Asynchronously finalize the sequence track encoding.

encode_sequence_image 

encode_sequence_image(image: HeifImage, encoder: Union[HeifEncoder, AsyncHeifEncoder], save_alpha: bool = False) -> None

Append a frame to the sequence track.

encode_sequence_image_async 

encode_sequence_image_async(image: HeifImage, encoder: Union[HeifEncoder, AsyncHeifEncoder], save_alpha: bool = False) -> None

Asynchronously append a frame to the sequence track.

rewind 

rewind() -> None

Rewind sequence track playback back to frame 0.

rewind_async 

rewind_async() -> None

Asynchronously rewind sequence track playback back to frame 0.