Media

Add images, movies, and audio, and control how they play.

Audio

class creator_studio_doc_format.core.Audio(*, preset_identifier='', identifier=None, geometry=None, aspect_ratio_locked=False, description=None, resource, playback_options, native_audio_recording=False, **extra_data)[source]

A sound attached to a slide.

An audio object has no visible size of its own; it appears as a fixed-size icon, so Keynote ignores the size in geometry and only uses the position.

field identifier : str | None = None

An identifier for this object that other objects use to refer to it. This identifier must be unique across the whole document.

field geometry : Geometry | None = None

The object’s position and size. If this value is absent, Keynote places the object automatically, with a default position and size for its kind.

field aspect_ratio_locked : bool = False

A Boolean value that indicates whether the object’s width-to-height ratio is locked when the object resizes. The lock doesn’t constrain the geometry property. If this property is absent, images, movies, and groups default to true, and other objects to false.

field description : str | None = None

The accessibility description for the object, read aloud by assistive technologies such as VoiceOver.

field resource : Resource [Required]

The resource that contains the audio data. If the resource isn’t playable on the device, has no audio track, or contains video, the object has no effect.

field playback_options : PlaybackOptions [Required]

The playback settings for the audio, such as volume, start and end trim times, looping, and whether playback continues across slides.

field native_audio_recording : bool = False

A Boolean value that indicates whether to treat the audio as recorded into the document rather than imported as a sound file. Recorded audio can’t loop back and forth, and instead plays from beginning to end: when this value is true, a Loop Back and Forth setting is replaced with no looping.

Image

class creator_studio_doc_format.core.Image(*, preset_identifier='', identifier=None, geometry=None, aspect_ratio_locked=True, description=None, title=None, title_is_positioned_on_top=True, caption=None, resource, mask=None, instant_alpha_path=None, stroke=Stroke(empty=True), opacity=1, shadow=Override.not_set(), reflection=None, is_placeholder=False, was_media_replaced=False, **extra_data)[source]

A picture defined by a resource with optional styling.

When geometry is absent, the reader places the image at the natural size of resource. When Keynote exports a presentation, it writes an object the format has no type for as an image. A 3D object, a drawing, an image gallery, a web video, a live video, or a comment on a slide becomes a picture of the object as it appears, with its rotation, flip, title, and caption drawn in, so the image has no title or caption, and its geometry is an unrotated rectangle enclosing the whole picture, including any shadow or reflection. Keynote also writes such an image without a description, so the object’s accessibility description is lost. A comment appears in its image only if comments are shown when someone exports the presentation; otherwise the image is empty.

field identifier : str | None = None

An identifier for this object that other objects use to refer to it. This identifier must be unique across the whole document.

field geometry : Geometry | None = None

The object’s position and size. If this value is absent, Keynote places the object automatically, with a default position and size for its kind.

field aspect_ratio_locked : bool = True

Whether the image’s width-to-height ratio is locked when the image is resized. The lock doesn’t constrain the geometry property. The default is true.

field description : str | None = None

The accessibility description for the object, read aloud by assistive technologies such as VoiceOver.

field title : Label | None = None

The object’s title.

field title_is_positioned_on_top : bool = True

When true, the title appears above the object; when false, the title appears below the object, above the caption if there is one. Defaults to true. Keynote ignores this when the object has none, or when it’s hidden with Label.is_visible set to false; Keynote places a hidden title above the object, where it appears when it shows again.

field caption : Label | None = None

The object’s caption, which Keynote always places below the object. If a caption is off, you still write it out with Label.is_visible set to false, so having a value doesn’t mean the caption shows.

field resource : Resource [Required]

The resource containing the image’s data. The resource data must decode to a single-frame image; use Movie for multi-frame images. A multi-frame animated image, such as an animated GIF, is rejected and the object is dropped. When Keynote writes an image changed with Adjust Image, the resource holds the image with those changes applied, not the original.

field mask : Mask | None = None

A cropping mask that is applied to the image before it’s shown. The mask’s geometry is the visible frame, while the image’s own geometry places the image resource. Decorations are shown relative to the intersection of the mask and the image. If absent, the image isn’t cropped.

field instant_alpha_path : InstantAlphaPath | None = None

A cropping path applied to the image before it’s shown, removing the image’s background.

field stroke : Stroke = Stroke(empty=True)

A border stroke drawn around the image. Defaults to no border.

field opacity : float = 1

The image’s opacity, in the range 0 to 1.

field shadow : Override[Shadow] = Override.not_set()

The shadow shown beneath the image.

field reflection : Reflection | None = None

The reflection shown for the image.

field is_placeholder : bool = False

Whether this image is a media placeholder, meant to be replaced with another image. When false, was_media_replaced is ignored and treated as false.

field was_media_replaced : bool = False

If this image is a placeholder, whether the resource in it was replaced.

Mask

class creator_studio_doc_format.core.Mask(*, preset_identifier='', geometry=None, path=None, **extra_data)[source]

The crop applied to an image, clipping the resource to a path within the mask’s own geometry.

The part outside the crop is retained in the file rather than trimmed away. A mask whose path encloses no area would hide the image completely, so it’s discarded when it’s read, and the image isn’t cropped.

field geometry : Geometry | None = None

The geometry of the frame used to crop the image’s resource, in the same coordinate space as the image’s own geometry. Either this or path must be present.

field path : Path | None = None

The path used to crop the image’s resource, anchored within geometry if present. Either this or geometry must be present; if absent and geometry is used, the path is assumed to be rectangular.

InstantAlphaPath

class creator_studio_doc_format.core.InstantAlphaPath(*, preset_identifier='', path, size=None, **extra_data)[source]

A masking path applied to an image to clip out its background, with only the area it encloses shown.

A path that comes out empty, encloses no area, or lies outside the image is discarded, and the image keeps its background.

field path : str [Required]

The outline of the visible area, in the syntax of an SVG <path> element’s d attribute, with these differences: only the moveto (M), lineto (L), cubic and quadratic curveto (C and Q), and closepath (Z) commands are read; every segment must have its own command letter; separators must be spaces; and a lowercase command is read as absolute rather than relative. The value must begin with a moveto command. Reading stops at the first token that can’t be read; the outline up to there is kept, including the interrupted segment, with its missing numbers taken as 0.

field size : Size | None = None

If present, path is treated as relative to a rectangle at the origin with this size, and then stretched to cover the natural size of the image. If absent, it’s assumed to equal the natural size of the image.

Movie

class creator_studio_doc_format.core.Movie(*, preset_identifier='', identifier=None, geometry=None, aspect_ratio_locked=True, description=None, title=None, title_is_positioned_on_top=True, caption=None, resource, poster_image=None, poster_time=Duration(seconds=0.0), playback_options, stroke=Stroke(empty=True), opacity=1, shadow=Override.not_set(), reflection=None, **extra_data)[source]

A movie or animated image defined by a resource with optional styling.

When geometry is omitted, the object takes the resource’s natural size, falling back to 640 × 480 points when the reader cannot measure that size. Placed inline in the text of a text box or shape, an unplayable movie removes that whole text box or shape, including all of its text; in a slide’s presenter notes, it stops the document from loading.

field identifier : str | None = None

An identifier for this object that other objects use to refer to it. This identifier must be unique across the whole document.

field geometry : Geometry | None = None

The object’s position and size. If this value is absent, Keynote places the object automatically, with a default position and size for its kind.

field aspect_ratio_locked : bool = True

Whether the movie’s width-to-height ratio is locked when the movie is resized. The lock doesn’t constrain the geometry property. The default is true.

field description : str | None = None

The accessibility description for the object, read aloud by assistive technologies such as VoiceOver.

field title : Label | None = None

The object’s title.

field title_is_positioned_on_top : bool = True

When true, the title appears above the object; when false, the title appears below the object, above the caption if there is one. Defaults to true. Keynote ignores this when the object has none, or when it’s hidden with Label.is_visible set to false; Keynote places a hidden title above the object, where it appears when it shows again.

field caption : Label | None = None

The object’s caption, which Keynote always places below the object. If a caption is off, you still write it out with Label.is_visible set to false, so having a value doesn’t mean the caption shows.

field resource : Resource [Required]

The resource containing the movie’s data. The resource must decode to a multi-frame animated image or to a movie with a video track, playable on the device where the file is imported; if not, the object is skipped.

field poster_image : Resource | None = None

The resource containing the data for the movie’s poster image. The poster image is shown when the movie isn’t playing; this resource is used only as a fallback when a poster image can’t be generated from poster_time.

field poster_time : Duration = Duration(seconds=0.0)

A time, limited to the movie’s duration, used to determine which frame of the movie is shown when the movie isn’t playing. The default is 0, the first frame, which is also used for a negative or otherwise unusable time.

field playback_options : PlaybackOptions [Required]

Playback settings for the movie, such as volume, start and end trim times, looping, and whether playback continues across slides.

field stroke : Stroke = Stroke(empty=True)

The border stroke drawn around the movie. The default is no border.

field opacity : float = 1

The opacity value of the movie, in the range 0 to 1.

field shadow : Override[Shadow] = Override.not_set()

The shadow shown beneath the movie.

field reflection : Reflection | None = None

The reflection shown for the movie.

PlaybackOptions

class creator_studio_doc_format.core.PlaybackOptions(*, preset_identifier='', volume=1, start_time=None, end_time=None, loop_option=LoopOption.NONE, plays_across_slides=False, **extra_data)[source]

Options controlling playback of media.

field volume : float = 1

The audio volume for playback, where 0.0 is silent and 1.0 is full volume.

Constraints:
  • ge = 0

  • le = 1

field start_time : Duration | None = None

The playback start time. If it’s absent, negative, or later than the end of the media, playback starts at the beginning.

field end_time : Duration | None = None

The playback end time. If it’s absent, later than the end of the media, or earlier than start_time, playback continues to the end of the media.

field loop_option : LoopOption = LoopOption.NONE

How playback repeats after reaching the end time.

field plays_across_slides : bool = False

Whether the media plays across slides.

LoopOption

class creator_studio_doc_format.core.LoopOption(str, Enum)[source]

The behavior of playback when it reaches the end time.

A field accepts a member or its value, so LoopOption.BACK_AND_FORTH and 'back_and_forth' are the same. The member’s name as a string isn’t accepted.

BACK_AND_FORTH = 'back_and_forth'

Plays the media repeatedly forward from start_time to end_time and then backward from end_time to start_time. Not supported by all media; none is used instead. Shown in Keynote as Loop Back and Forth.

NONE = 'none'

Plays the media once through and then stops.

REPEATING = 'repeating'

Plays the media repeatedly from start_time to end_time. Shown in Keynote as Loop.

Duration

class creator_studio_doc_format.core.Duration(*, preset_identifier='', seconds=None, **extra_data)[source]

A length of time.

The only representation is a number of seconds.

field seconds : float | None = None

A length of time in seconds.

See also

Add an image