avitem
AVItem object
Section titled “AVItem object”app.project.item(index)
Description
Section titled “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
Section titled “Attributes”AVItem.duration
Section titled “AVItem.duration”app.project.item(index).duration
Description
Section titled “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.
Floating-point value, in the range [0.0..10800.0]; read/write for a CompItem; otherwise, read-only.
AVItem.footageMissing
Section titled “AVItem.footageMissing”app.project.item(index).footageMissing
Description
Section titled “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.
Boolean; read-only.
AVItem.frameDuration
Section titled “AVItem.frameDuration”app.project.item(index).frameDuration
Description
Section titled “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.
Floating-point value, in the range [1/99..1.0]; read-only for a FootageItem, otherwise read/write.
AVItem.frameRate
Section titled “AVItem.frameRate”app.project.item(index).frameRate
Description
Section titled “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.
Floating-point value, in the range [1.0..99.0]; read-only for a FootageItem, otherwise read/write.
AVItem.hasAudio
Section titled “AVItem.hasAudio”app.project.item(index).hasAudio
Description
Section titled “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.
Boolean; read-only.
AVItem.hasVideo
Section titled “AVItem.hasVideo”app.project.item(index).hasVideo
Description
Section titled “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.
Boolean; read-only.
AVItem.height
Section titled “AVItem.height”app.project.item(index).height
Description
Section titled “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.
Integer, in the range [1..30000]; read/write, except as noted.
AVItem.isMediaReplacementCompatible
Section titled “AVItem.isMediaReplacementCompatible”app.project.item(index).isMediaReplacementCompatible
Description
Section titled “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.
Boolean; read only.
AVItem.name
Section titled “AVItem.name”app.project.item(index).name
Description
Section titled “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.
String; read/write.
AVItem.pixelAspect
Section titled “AVItem.pixelAspect”app.project.item(index).pixelAspect
Description
Section titled “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 |
Floating-point value, in the range [0.01..100.0]; read/write.
AVItem.proxySource
Section titled “AVItem.proxySource”app.project.item(index).proxySource
Description
Section titled “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().
FootageSource object; read-only.
AVItem.time
Section titled “AVItem.time”app.project.item(index).time
Description
Section titled “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).
Floating-point value; read/write.
AVItem.usedIn
Section titled “AVItem.usedIn”app.project.item(index).usedIn
Description
Section titled “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.
Array of CompItem objects; read-only.
AVItem.useProxy
Section titled “AVItem.useProxy”app.project.item(index).useProxy
Description
Section titled “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.
Boolean; read/write.
AVItem.width
Section titled “AVItem.width”app.project.item(index).width
Description
Section titled “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.
Integer, in the range [1..30000]; read/write, except as noted.
Methods
Section titled “Methods”AVItem.setProxy()
Section titled “AVItem.setProxy()”app.project.item(index).setProxy(file)
Description
Section titled “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
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
file | Extendscript File object | The file to be used as a proxy. |
Returns
Section titled “Returns”None.
AVItem.setProxyToNone()
Section titled “AVItem.setProxyToNone()”app.project.item(index).setProxyToNone()
Description
Section titled “Description”Removes the proxy from this AVItem, sets the value of proxySource to null, and sets the value of useProxy to false.
Parameters
Section titled “Parameters”None.
Returns
Section titled “Returns”Nothing.
AVItem.setProxyWithPlaceholder()
Section titled “AVItem.setProxyWithPlaceholder()”app.project.item(index).setProxyWithPlaceholder(name, width, height ,frameRate, duration)
Description
Section titled “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
Section titled “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
Section titled “Returns”Nothing.
AVItem.setProxyWithSequence()
Section titled “AVItem.setProxyWithSequence()”app.project.item(index).setProxyWithSequence(file,forceAlphabetical)
Description
Section titled “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
Section titled “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
Section titled “Returns”Nothing.
AVItem.setProxyWithSolid()
Section titled “AVItem.setProxyWithSolid()”app.project.item(index).setProxyWithSolid(color, name, width, height, pixelAspect)
Description
Section titled “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
Section titled “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
Section titled “Returns”Nothing.