AVItem object
app.project.item(index)
The AVItem object provides access to attributes and methods of audio/visual files imported into After Effects.
-
AVItem is a subclass of Item. All methods and attributes of Item, in addition to those listed below, are available when working with AVItem.
-
AVItem is the base class for both CompItem and FootageItem, so AVItem attributes and methods are also available when working with CompItem and FootageItem objects.
Attributes
| Attribute | Description |
|---|---|
| name | The name of the object as shown in the Project panel. |
| width | The width of the item. |
| height | The height of the item. |
| pixelAspect | The pixel aspect ratio of the item. |
| frameRate | The frame rate of the item. |
| frameDuration | The frame duration for the item. |
| duration | The total duration of the item. |
| useProxy | When true, a proxy source is used for this item. |
| proxySource | The FootageItem object used as proxy for the item. |
| time | Current time of the item. |
| usedIn | The CompItem objects that use this item. |
| hasVideo | When true, the item has a video component. |
| hasAudio | When true, the item has an audio component. |
| footageMissing | When true, the item cannot be found or is a placeholder. |
Methods
| Method | Description |
|---|---|
| setProxy() | Sets a proxy for the item. |
| setProxyWithSequence() | Sets a sequence as a proxy for the item. |
| setProxyWithSolid() | Sets a solid as a proxy for the item. |
| setProxyWithPlaceholder() | Sets a placeholder as a proxy for the item. |
| setProxyToNone() | Removes the proxy for the item. |
Detailed Description
duration attribute
app.project.item(index).duration
Returns the duration, in seconds, of the item. Still footage items have a duration of 0.
- In a CompItem, the value is linked to the duration of the composition, and is read/write.
- In a FootageItem, the value is linked to the duration of the mainSource object, and is read-only.
Type: Floating-point value in the range [0.0..10800.0] read/write for a CompItem, otherwise, read-only
footageMissing attribute
app.project.item(index).footageMissing
When true, the AVItem is a placeholder, or represents footage with a source file that cannot be found. In this case, the path of the missing source file is in the missingFootagePath attribute of the footage item’s source-file object. See “FootageItem mainSource attribute” on page 66 and “FileSource missingFootagePath attribute” on page 61.
Type: Boolean read-only
frameDuration attribute
app.project.item(index).frameDuration
Returns the length of a frame for this AVItem, in seconds. This is the reciprocal of frameRate. When set, the reciprocal is automatically set as a new frameRate value. This attribute returns the reciprocal of the frameRate, which may not be identical to a value you set, if that value is not evenly divisible into 1.0 (for example, 0.3). Due to numerical limitations, (1 / (1 / 0.3)) is close to, but not exactly, 0.3. If the AVItem is a FootageItem, this value is linked to the mainSource, and is read-only. To change it, set the conformFrameRate of the mainSource object. This sets both the frameRate and frameDuration of the FootageItem.
Type: Floating-point value in the range [1/99.. 1.0] read-only for a FootageItem, otherwise read/write
frameRate attribute
app.project.item(index).frameRate
The frame rate of the AVItem, in frames-per-second. This is the reciprocal of the frameDuration. When set, the reciprocal is automatically set as a new frameDuration value.
- In a CompItem, the value is linked to the frameRate of the composition, and is read/write.
- In a FootageItem, the value is linked to the frameRate of the mainSource object, and is read-only. To change it, set the conformFrameRate of the mainSource object. This sets both the frameRate and frameDuration of the FootageItem.
Type: Floating-point value in the range [1.0..99.0] read-only for a FootageItem, otherwise read/write
hasAudio attribute
app.project.item(index).hasAudio
When true, the AVItem has an audio component.
- In a CompItem, the value is linked to the composition.
- In a FootageItem, the value is linked to the mainSource object.
Type: Boolean read-only
hasVideo attribute
app.project.item(index).hasVideo
When true, the AVItem has an video component.
- In a CompItem, the value is linked to the composition.
- In a FootageItem, the value is linked to the mainSource object.
Type: Boolean read-only
height attribute
app.project.item(index).height
The height of the item in pixels.
- In a CompItem, the value is linked to the composition, and is read/write.
- In a FootageItem, the value is linked to the mainSource object, and is read/write only if the mainSource object is a SolidSource. Otherwise, it is read-only.
Type: Integer in the range [1...30000] read/write, except as noted
name attribute
app.project.item(index).name
The name of the item, as shown in the Project panel.
- In a FootageItem, the value is linked to the mainSource object. If the mainSource object is a FileSource, this value controls the display name in the Project panel, but does not affect the file name.
Type: String read/write
pixelAspect attribute
app.project.item(index).pixelAspect
The pixel aspect ratio (PAR) of the item.
- In a CompItem, the value is linked to the composition.
- In a FootageItem, the value is linked to the mainSource object.
The value you retrieve after setting may be slightly different from the value you supplied. The following table compares the value as it appears in the UI with the more-accurate value returned by this attribute.
| PAR in the After Effects UI | PAR returned by the pixelAspect attribute |
|---|---|
| 0.91 | 0.90909090909091 |
| 1 | 1 |
| 1.5 | 1.5 |
| 1.09 | 1.09401709401709 |
| 1.21 | 1.21212121212121 |
| 1.33 | 1.33333333333333 |
| 1.46 | 1.45868945868946 |
| 2 | 2 |
Type: Floating-point value, in the range [0.01..100.0] read/write
proxySource attribute
app.project.item(index).proxySource
The FootageSource being used as a proxy. The attribute is read-only; to change it, call any of the AVItem methods that change the proxy source: setProxy(), setProxyWithSequence(), setProxyWithSolid(), or setProxyWithPlaceholder().
Type: FootageSource object read-only
setProxy() method
app.project.item(index).setProxy(file)
Sets a file as the proxy of this AVItem. Loads the specified file into a new FileSource object, sets this as the value of the proxySource attribute, and sets useProxy to true. It does not preserve the interpretation param- eters, instead using the user preferences. If the file has an unlabeled alpha channel, and the user preference says to ask the user what to do, the method estimates the alpha interpretation, rather than asking the user.
This differs from setting a FootageItem's main source, but both actions are performed as in the user interface.
Parameters
- file An ExtendScript File object for the file to be used as a proxy.
Returns: None.
setProx yTo None() m etho d
app.project.item(index).setProxyToNone()
Removes the proxy from this AVItem, sets the value of proxySource to null, and sets the value of useProxy to false.
Parameters: None.
Returns: Nothing.
setProxyWithPlaceholder() method
app.project.item(index).setProxyWithPlaceholder(name, width, height, frameRate, duration)
Creates a PlaceholderSource object with specified values, sets this as the value of the proxySource attribute, and sets useProxy to true. It does not preserve the interpretation parameters, instead using the user prefer- ences.
NOTE: There is no direct way to set a placeholder as a proxy in the user interface; this behavior occurs when a proxy has been set and then moved or deleted.
Parameters:
- name A string containing the name of the new object.
- width, height The pixel dimensions of the placeholder, an integer in the range [4..30000].
- frameRate The frames-per-second, an integer in the range [1..99].
- duration The total length in seconds, up to 3 hours. An integer in the range [0.0..10800.0].
Returns: Nothing.
setProxyWithSequence() method
app.project.item(index).setProxyWithSequence(file, forceAlphabetical)
Sets a sequence of files as the proxy of this AVItem, with the option of forcing alphabetical order. Loads the specified file sequence into a new FileSource object, sets this as the value of the proxySource attribute, and sets useProxy to true. It does not preserve the interpretation parameters, instead using the user preferences. If any file has an unlabeled alpha channel, and the user preference says to ask the user what to do, the method estimates the alpha interpretation, rather than asking the user.
Parameters:
- file An ExtendScript File object for the first file in the sequence.
- forceAlphabetical When true, use the “Force alphabetical order” option.
Returns: Nothing.
setProxyWithSolid() method
app.project.item(index).setProxyWithSolid(color, name, width, height, pixelAspect)
Creates a SolidSource object with specified values, sets this as the value of the proxySource attribute, and sets useProxy to true. It does not preserve the interpretation parameters, instead using the user preferences.
NOTE: There is no way, using the user interface, to set a solid as a proxy; this feature is available only through scripting.
Parameters:
- color The color of the solid, an array of 3 floating-point values, [R, G, B], in the range [0.0..1.0].
- name A string containing the name of the new object.
- width, height The pixel dimensions of the placeholder, an integer in the range [1...30000].
- pixelAspect The pixel aspect of the solid, a floating-point value in the range [0.01... 100.0].
Returns: Nothing.
time attribute
app.project.item(index).time
The current time of the item when it is being previewed directly from the Project panel. This value is a number of seconds. Use the global method timeToCurrentFormat to convert it to a string value that expresses the time in terms of frames; see “timeToCurrentFormat() global function” on page 15. It is an error to set this value for a FootageItem whose mainSource is still (item.mainSource.isStill is true).
Type: Floating-point value read/write
usedIn attribute
app.project.item(index).usedIn
All the compositions that use this AVItem. Note that upon retrieval, the array value is copied, so it is not automatically updated. If you get this value, then add this item into another composition, you must retrieve the value again to get an array that includes the new item.
Type: Array of CompItem objects read-only
useProxy attribute
app.project.item(index).useProxy
When true, a proxy is used for the item. It is set to true by all the SetProxy methods, and to false by the SetProxyToNone() method.
Type: Boolean read/write
width attribute
app.project.item(index).width
The width of the item, in pixels.
- In a CompItem, the value is linked to the composition, and is read/write.
- In a FootageItem, the value is linked to the mainSource object, and is read/write only if the mainSource object is a SolidSource. Otherwise, it is read-only.
Type: Integer in the range [1...30000] read/write, except as noted