6.6 The shot vector transform
(New in Reveal X!)
The constructor works by allocating segments to the media items specified by the user in muvee Reveal’s media panel. Certain kinds of productions need more control over the structure of the input media in order to be possible. For example, a style may be wish to present three photos at a time. In such a case, you may not want the duration for which a three-photo composition is shown to be three times as long as the time the style would spend on a single photo. The shot vector transform mechanism permits you control over such aspects of the construction through the manipulation of shots passed by the user before the constructor gets to see them.
The shot vector transform is a function that takes a vector of shots and is expected to return a vector shots. The returned shot vector is what is seen by the constructor. The shots passed in the input can be reused in the output with or without modification. The function may also insert new shots or decide not to show certain shots specified by the user.
(define (muvee-shot-vector-transform shotvec) .... result-shotvec)
shotvec, as the name suggests, is a vector of shot objects and result-shotvec is the transformed shot vector. The simplest shot vector transform is therefore the identity function.
6.6.1 The shot object
The shot object represents a media item given by the user. It can be a photo, a segment video clip or an inter-title card.
Each photo is represented using its own shot object. So is each inter-title card.
Video clips have a more complicated relationship to the items specified by the user. All video clips are split up into shots according to a) the shot boundaries detected in the video, b) the excluded sections and c) highlights. Each highlight is assigned its own shot object and subsumes any shot boundaries within it. All excluded material is thrown away and does not have any representation in the shot vector.
The shot object provides access to some of the properties of the media items, some of which can be changed. In the code below we assume that shot stands for a shot object.
6.6.2 Basic shot properties
Full path to the media file.
A list of symbols indicating shot attributes. Symbols can be one or more of sync-boost, image, video or inter-title. To tell whether a shot is video, you can do (find 'video shot.attribs).
On input, contains the "minimum duration" setting indicated by the user for photos, taking into account both the global setting in the "Personalize" panel as well as any photo-specific setting. This field is irrelevant for video.
The unique ID (number) of the media panel item that this shot is associated with. All shots that were created from a single media panel item will have the same id property. This allows you to regroup the shots to be isomorphic to the media panel if so desired.
A list of the form (media-start-time media-end-time) that specifies the media interval within a video file that the shot represents. Applicable only to video shots and irrelevant for images and inter-titles.
A list of the form ((from1 to1 text1) (from2 to2 text2) ....) if the user has specified captions for the shot, or () if no caption is set for the shot. Photos will have at most one caption but videos can have more than one. Caption text might consist of a single line of text or two lines separated by a line break "\n"
If the shot is a highlight, then this will be a list of the form ((from to)). If the shot has no highlights or is not video, this property will be ().
6.6.3 Presentation properties
Shot objects have some properties that can be set to control their presentation in ways that can be more flexible than the muvee-segment-effect mechanism. All presentation properties of shots are unset upon input - i.e. only the shot vector transform can set these properties.
All presentation properties can be used with both put and get. However, when you do, say, (put shot.treatment my-fabulous-effect), it does not replace the previous property, but is combined with it to create a composite treatment. Since there is seldom any need for a style author to replace a presentation property after it being set, since only the shot vector transform can set it anyway, this auto-combination approach is more useful.
6.6.3.1 shot.treatment
A shot’s "treatment" is an effect that is applied to the media item prior to all other style specified effects - i.e. treatments are the "inner most" effects applied to media. Think "color treatment" and you’re be roughly there.
6.6.3.2 shot.presenter
Intended to provide total control over the presentation of segments assigned to this shot. A "presenter" function is of the form -
(fn (input-effect) ... output-effect)
In other words, a presenter is an effect transformer, which takes an effect (see About effects and transitions), munges it and returns another. The simplest presenter is therefore the identity function.
At construction time, if a shot has a presenter set, the constructor will pass it the effect specified using muvee-segment-effect and will use the effect returned by the presenter in place of that specification. This allows a presenter to override the segment effect for a single shot easily.
Presenters are combined at put time using simple function composition.
6.6.3.3 shot.entry-effect and shot.exit-effect
These are effects and their composition behaves similar to shot.treatment. The only difference is the times at which these effects are used. The shot.entry-effect is applied in addition to the segment presentation at the beginning of the first segment containing media from the shot. Similarly, the shot.exit-effect is applied in addition to the segment presentation at the end of the last segment containing media from the shot.
The constructor always shows media in the order specified in the media panel, therefore all the other segments showing media from the shot are guaranteed to appear between the segments containing exhibiting the entry effect and the exit effect.
6.6.4 Utility functions
Some utility functions are provided for creating new kinds of shots for use within the result shot vector. These allows a style to insert stock media, special algorithmically driven segments, etc. Note that all new shot objects must be given valid shot ids.
| (make-video path-to-file property-object) → shot-object |
| path-to-file : string |
| property-object : object |
| (make-image path-to-file property-object) → shot-object |
| path-to-file : string |
| property-object : object |
(make-image (resource "stock/art.jpg") (object () 'id shot.id 'min-duration-secs 20.0))