avitem
AVItem object
app.project.item(index)
Description
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. See Item object
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. See CompItem object and FootageItem object.
CompItems and FootageItems, while logical descendants of AVItem, are not really subclasses of AVItem as AVItem doesn’t exist in Extendscript, ie. attempting to check if item instanceof AVItem will fail because AVItem is undefined. This is also true for Item itself.
See Javascript Classes and After Effects Class Hierarchy for more info.
Attributes
AVItem.duration
app.project.item(index).duration
Description
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
durationof themainSourceobject, and is read-only.
Type
Floating-point value, in the range [0.0..10800.0]; read/write for a CompItem; otherwise, read-only.
AVItem.footageMissing
app.project.item(index).footageMissing
Description
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 and FileSource.missingFootagePath.
Type
Boolean; read-only.
AVItem.frameDuration
app.project.item(index).frameDuration
Description
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.
AVItem.frameRate
app.project.item(index).frameRate
Description
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
frameRateof the composition, and is read/write. - In a FootageItem, the value is linked to the
frameRateof themainSourceobject, and is read-only. To change it, set theconformFrameRateof themainSourceobject. This sets both theframeRateandframeDurationof the FootageItem.
Type
Floating-point value, in the range [1.0..99.0]; read-only for a FootageItem, otherwise read/write.
AVItem.hasAudio
app.project.item(index).hasAudio
Description
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
mainSourceobject.
Type
Boolean; read-only.
AVItem.hasVideo
app.project.item(index).hasVideo
Description
When true, the AVItem has a video component.
- In a CompItem, the value is linked to the composition.
- In a FootageItem, the value is linked to the
mainSourceobject.
Type
Boolean; read-only.
AVItem.height
app.project.item(index).height
Description
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
mainSourceobject, and is read/write only if themainSourceobject is a SolidSource. Otherwise, it is read-only.
Type
Integer, in the range [1..30000]; read/write, except as noted.
AVItem.isMediaReplacementCompatible
app.project.item(index).isMediaReplacementCompatible
Description
Test whether the AVItem can be used as an alternate source when calling Property.setAlternateSource().
Returns true if the item can be used, or otherwise false.
A CompItem or a FootageItem can be used as an alternate source for the layer, with some restrictions:
- If the AVItem is a FootageItem object, then FootageItem.FootageSource should not be a SolidSource object.
- If the AVItem is a FootageItem object and the FootageItem.FootageSource is a FileSource object then that FileSource should not point to a non-media file e.g. a JSX script file.
- Setting the AVItem cannot create a cyclical reference within the project.
Type
Boolean; read only.
AVItem.name
app.project.item(index).name
Description
The name of the item, as shown in the Project panel.
- In a FootageItem, the value is linked to the
mainSourceobject. If themainSourceobject is aFileSource, this value controls the display name in the Project panel, but does not affect the file name.
Type
String; read/write.
AVItem.pixelAspect
app.project.item(index).pixelAspect
Description
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.909091 |
| 1 | 1 |
| 1.5 | 1.5 |
| 1.09 | 1.09402 |
| 1.21 | 1.21212 |
| 1.33 | 1.33333 |
| 1.46 | 1.45869 |
| 2 | 2 |
Type
Floating-point value, in the range [0.01..100.0]; read/write.
AVItem.proxySource
app.project.item(index).proxySource
Description
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.
AVItem.time
app.project.item(index).time
Description
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. 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.
AVItem.usedIn
app.project.item(index).usedIn
Description
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.
AVItem.useProxy
app.project.item(index).useProxy
Description
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.
AVItem.width
app.project.item(index).width
Description
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
mainSourceobject, and is read/write only if themainSourceobject is a SolidSource. Otherwise, it is read-only.
Type
Integer, in the range [1..30000]; read/write, except as noted.
Methods
AVItem.setProxy()
app.project.item(index).setProxy(file)
Description
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 parameters, 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 mainSource, but both actions are performed as in the user interface.
Parameters
| Parameter | Type | Description |
|---|---|---|
file | Extendscript File object | The file to be used as a proxy. |
Returns
None.
AVItem.setProxyToNone()
app.project.item(index).setProxyToNone()
Description
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.
AVItem.setProxyWithPlaceholder()
app.project.item(index).setProxyWithPlaceholder(name, width, height ,frameRate, duration)
Description
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 preferences.
Parameters
| Parameter | Type | Description |
|---|---|---|
name | String | The name of the new object. |
width | Integer, in the range [4..30000] | The pixel dimensions of the placeholder. |
height | Integer, in the range [4..30000] | The pixel dimensions of the placeholder. |
frameRate | Integer, in the range [1..99] | Frame rate for the proxy. |
duration | Integer, in the range [0.0..10800.0] | The total length in seconds, up to 3 hours. |
Returns
Nothing.
AVItem.setProxyWithSequence()
app.project.item(index).setProxyWithSequence(file,forceAlphabetical)
Description
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
| Parameter | Type | Description |
|---|---|---|
file | Extendscript File object | The first file in the sequence. |
forceAlphabetical | Boolean | When true, use the “Force alphabetical order” option. |
Returns
Nothing.
AVItem.setProxyWithSolid()
app.project.item(index).setProxyWithSolid(color, name, width, height, pixelAspect)
Description
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.
Parameters
| Parameter | Type | Description |
|---|---|---|
color | Array of three floating-point values, [R, G, B], in the range [0.0..1.0]. | The color of the solid. |
name | String | The name of the new object. |
width, height | Integer, in the range [1..30000] | The pixel dimensions of the placeholder. |
pixelAspect | Floating-point value, in the range [0.01..100.0] | The pixel aspect ratio of the solid. |
Returns
Nothing.