Container Clips

## Container Clips Concept

A Container Clip is a Media Item and the Timeline Clip made from it that has three items packed together as a single entity: Program, Unrendered Media and Rendered Media.

### Components

1. Unrendered Media This is what is displayed on timeline if container clip media is not rendered.
2. Program This data is used to render a media clip on timeline, sometimes using unrendered media as input.
3. Rendered Media This is what is displayed on timeline when Container Clip is rendered.

## Rationale

- Performance

  Container Clips provide means to turn resource heavy media items such as Sequence Clips into rendered media

- Resource Management

  For example Blender Projects and G'Mic scripts are nicely managed by having them available via Container Clips

- Capablity extension

  Existing technologies and applications can made to provide functionality that is not available otherwise. There will be more developments in this area in the future.

- Sharing

  In the future we will create a central repository to share container clip resources.

## Workflow

1. Create Container Clip Media Item using Project -> Create Contaniner Clip menu.
2. Edit properties of Container Clip with Right Mouse menu selection Edit Container Data if available.
3. Add Container Clip on Timeline.
4. Render and manage Container Clips on Timeline with Right Mouse submenu Container Clip Actions.

## Container Clip Types

### G'Mic Script Container Clips

##### Components

- Unrendered Media Video Clip.
- Program G'Mic script created and saved from G'Mic tool.
- Rendered Media A clip rendered with G'mic effect.

##### Use Cases

- Render G'Mic effects only on clip ranges used on timeline.
- Make easier to use single user defined G'Mic effect on multple clips.

##### Creating G'Mic Script Container Clips

1. Open G'Mic tool.
2. Create G'Mic effect script. See section on G'Mic Effects in Chapter Tools.
3. Press Save Script button in bottom left corner and save effect.
4. Select menu item Project -> Create Contaniner Clip -> From G'Mic Script.
5. Select the script you saved and the clip that it will be applied on to create Container Clip.

### Blender Project Container Clips

##### Components

- Unrendered Media A placeholder Video Clip rendered on Media item creation.
- Program Project file with *blend extension.
- Rendered Media Rendered Clipfrom project file.

##### Use Cases

- Manage Blender projects by having handles for them in Flowblade.
- Create editors for Blender projects so that users can edit their properies on Flowblade
- Make possible to contribute and shear interesting Blender Projects for e.g. so nice text effects.

##### Creating Blender Project Container Clips

1. Select menu item Project -> Create Contaniner Clip -> From Blender Project and select Blender project file with .blend extension.
2. You can edit values that Blender project is rendered with, see section Edíting Container Programs below.

### Selection Container Clips

##### Components

- Unrendered Media A MLT XML vdieo clip created from selection or sequence like Compound clips previously.
- Program A MLT XML video clip created from selection or sequence like Compound clips previously. Here Program is the same as unrendered media.
- Rendered Media Clip Rendered from MLT XML Clip.

##### Use Cases

- Make possible to create Media items from selections and full Sequences.
- Give better timeline performance for complex multitrack container clips by pre-rendering them on timeline.

##### Creating Selection Container Clip from Selection

1. Select 2 or more adjacent clips from a single track.
2. Select Project->Create Container Clip->From Selected Clips
3. A new Media Item appears in the current Bin.

##### Creating Selection Container Clip from Sequence

1. Select Project->Create Container Clip->From Current Sequence
2. A new Media Item appears in the current Bin.

##### Creating audio synced Selection Container Clip from two Media Items

1. Select 2 Media Items in Media panel.
   - The expected case is to select 1 Video and 1 Audio Clip.
   - If you select 2 Video Clips then which is used as video depends on selection order.
   - Audio from clip treated as video is muted.
2. Select Project->Create Compound Clip->Audio Sync Merge Clip From 2 Media Items
3. If audio sync is successful a dialog appers. Give a name for the new Media Item in the dialog.
4. A new Media Item appears in the current Bin.

Audio syncing looks for best matemathical match between two audio waveforms, so audio syncing non-matching audio will produce random results.

## Creating Editable Blender Container Programs

It is possible to create and add editors to Blender Container Clips that allow users to change the rendered output.

Feature uses Blender Python API and runs a script before output is rendered to change attribute values of Blender scene objects.

This is an advanced feature and requires a working knowledge on scripting using Blender's Python API.

#### Editable Objects

Three types of objects are currently availabe to be user edited using this functionality.

- Objects are bpy.data.objects objects available for Python scripts.
- Curves are bpy.data.curves objects available for Python scripts.
- Materials are bpy.data.materials objects available for Python scripts.

#### Editors

Five different types of editors are currently availabe for editing object attributes.

- String editor outputs a quoted string in the launch script.
- Int editor outputs an integer number in the launch script.
- Float editor outputs a float number in the launch script.
- Color editor outputs a sequence of 4 comma separated floats that define a color.
- Value editor outputs a non-quoted string in the launch script. That can be used as value to any attribute.

### Example

In this example we create String and Color editors to change text and color rendered from Blender Project file.

#### Step 1: Find out object and attribute names using Blenders Script view

Scene and sript panel from Blender with our test project open.

Here we have established that:

- We need to edit object bpy.data.curves["Title1"] attribute body to set text string.
- We need to edit object bpy.data.materials["Title1.material"] attribute diffuse_color to set text color.

#### Step 2: Edit Container Program Edit Data

With this information we can create the editors that allow editing text and color of clips rendered from this project.

- Create Blender Container clip clip from your project.
- Right click the created Media item and select: Edit Container Program Edit Data

- To create the text editor we give following data in the dialog, notice how it corresponds with the earlier information.

- To create the color editor we give following data in the dialog.

- Remember to press Add Editor to save given data as an editor.

#### Step 3: Set values for timeline clips

- Make a Timeline Clip .

- Right click the clip and select Container Clip Actions->Edit Container Program and edit data in the dialog.

#### Launch script

The editors in this example create the code lines below that set attribute values in the lauch script before render start.

obj = bpy.data.materials["Title1.Material"]

obj.diffuse_color = 0.9882352941176471,0.6862745098039216,0.24313725490196078,1.0

obj = bpy.data.curves["Title1"]

obj.body = "Yesh, this was edited!"