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
geometryand 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
geometryproperty. If this property is absent, images, movies, and groups default totrue, and other objects tofalse.
-
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.
-
field identifier : str | None =
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
geometryis absent, the reader places the image at the natural size ofresource. 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 notitleorcaption, and itsgeometryis an unrotated rectangle enclosing the whole picture, including any shadow or reflection. Keynote also writes such an image without adescription, 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
geometryproperty. The default istrue.
-
field description : str | None =
None¶ The accessibility description for the object, read aloud by assistive technologies such as VoiceOver.
-
field title_is_positioned_on_top : bool =
True¶ When
true, the title appears above the object; whenfalse, the title appears below the object, above the caption if there is one. Defaults totrue. Keynote ignores this when the object has none, or when it’s hidden withLabel.is_visibleset tofalse; 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_visibleset tofalse, 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
Moviefor 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
geometryis the visible frame, while the image’s owngeometryplaces 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
0to1.
-
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_replacedis ignored and treated asfalse.
-
field was_media_replaced : bool =
False¶ If this image is a placeholder, whether the resource in it was replaced.
-
field identifier : str | None =
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.
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
paththat 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’sdattribute, with these differences: only the moveto (M), lineto (L), cubic and quadratic curveto (CandQ), 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.
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
geometryis 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
geometryproperty. The default istrue.
-
field description : str | None =
None¶ The accessibility description for the object, read aloud by assistive technologies such as VoiceOver.
-
field title_is_positioned_on_top : bool =
True¶ When
true, the title appears above the object; whenfalse, the title appears below the object, above the caption if there is one. Defaults totrue. Keynote ignores this when the object has none, or when it’s hidden withLabel.is_visibleset tofalse; 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_visibleset tofalse, 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
0to1.
-
field reflection : Reflection | None =
None¶ The reflection shown for the movie.
-
field identifier : str | None =
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.
-
field volume : float =
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_FORTHand'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_timetoend_timeand then backward fromend_timetostart_time. Not supported by all media;noneis 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_timetoend_time. Shown in Keynote as Loop.
-
BACK_AND_FORTH =
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.
-
field seconds : float | None =
See also