• Author / Uploaded
• Martha Cruz

• Categories
• Script Java
• Interfaz de línea de comando
• Archivo de computadora
• Lenguaje de programación
• Software

Citation preview

GUÍA DE SECUENCIAS DE COMANDOS

© Copyright 2007 Adobe Systems Incorporated. Reservados todos los derechos. Guía de secuencias de comandos Adobe®Creative Suite 3 After Effects® de Adobe® AVISO: Toda la información contenida en este documento es propiedad de Adobe Systems Incorporated. Queda prohibida la reproducción y transmisión de cualquier parte de esta publicación (ya sea en formato impreso o electrónico) en cualquier forma o por cualquier medio (electrónico, mecánico, fotocopiado, grabación o de otro tipo) sin el consentimiento previo y por escrito de Adobe Systems Incorporated. El software descrito en este documento se proporciona bajo licencia y sólo puede utilizarse o copiarse de acuerdo con los términos de dicha licencia. Esta publicación y la información que contiene se proporciona TAL CUAL, está sujeta a cambios sin previo aviso y no debe interpretarse como un compromiso por parte de Adobe Systems Incorporated. Adobe Systems Incorporated no asume ninguna responsabilidad ni compromiso por errores o inexactitudes, no ofrece garantía de ningún tipo (ya sean expresas, implícitas o legales) respecto a esta publicación y niega expresamente todas las garantías de comerciabilidad, adaptación para un propósito particular y no-infracción de derechos de terceros. Cualquier referencia a nombres de empresas en las plantillas de ejemplo tiene sólo fines informativos y no pretende referirse a ninguna organización real. Adobe, el logotipo de Adobe, After Effects, Photoshop y Bridge son marcas comerciales o marcas registradas de Adobe Systems Incorporated en Estados Unidos y en otros países. Apple, Mac, Macintosh y Mac OS son marcas comerciales de Apple Computer, Inc. registradas en Estados unidos y otros países. Microsoft y Windows son marcas comerciales registradas o marcas comerciales de Microsoft Corporation en Estados Unidos y otros países. JavaScript y todas las marcas relativas a Java son marcas comerciales o marcas comerciales registradas de Sun Microsystems, Inc. en Estados Unidos y en otros países. UNIX es una marca comercial registrada de The Open Group. Cualquier otra marca comercial pertenece a sus propietarios respectivos. Si esta guía se distribuye con software que incluye un contrato de licencia de usuario final, la guía, así como el software que en ella se describe, se proporcionan bajo licencia y pueden utilizarse o copiarse sólo de acuerdo con los términos de dicha licencia. Exceptuando lo permitido por tal licencia, se prohíbe reproducir, almacenar en un sistema de recuperación o transmitir cualquier parte de esta guía, en cualquier forma o por cualquier medio, ya sea electrónico, mecánico, en grabación o de otra forma, sin el previo consentimiento por escrito por parte de Adobe Systems Incorporated. Tenga en cuenta que el contenido de esta guía está protegido por leyes de derechos de autor (copyright), aunque no se distribuya con software que incluya un contrato de licencia de usuario final. El contenido de esta guía se proporciona sólo con fines informativos, está sujeto a cambios sin previo aviso y no debe interpretarse como un compromiso por parte de Adobe Systems Incorporated. Adobe Systems Incorporated no asume ninguna responsabilidad o compromiso por errores o inexactitudes que puedan aparecer en el contenido informativo de esta guía. Adobe Systems Incorporated, 345 Park Avenue, San José, California 95110, EE.UU.

Introducción

La Guía de secuencias de comandos de After Effects muestra cómo obtener un control de los procedimientos de los proyectos de After Effects mediante secuencias de comandos. Este conjunto de funciones está disponible en Adobe® After Effects® CS3 Professional. Mediante las secuencias de comandos del sistema, puede simplificar la canalización de procesos y evitar tener que seleccionar y hacer clic repetidamente. Si ha utilizado expresiones u otras técnicas similares a JavaScript para la animación o ha trabajado con secuencias de comandos del sistema en AppleScript o Visual Basic, reconocerá la eficacia de las secuencias de comandos en After Effects. Con práctica y experiencia suficiente en el lenguaje JavaScript, podrá controlar la canalización de los gráficos.

Si no está familiarizado con las secuencias de comandos After Effects es una herramienta visual con una interfaz de usuario gráfica; usted está acostumbrado a interactuar con ella mediante elementos de la interfaz, como menús, paneles e iconos. Para la mayor parte, ésta es la manera más fácil de trabajar. Las secuencias de comandos están diseñadas para situaciones en las que esta metodología conlleva numerosas repeticiones o laboriosas búsquedas y ordenaciones que se pueden automatizar. Las secuencias de comandos pueden aliviar tareas tediosas que, de otra manera, implicarían seleccionar y hacer clic muchas veces. También resultan útiles para aprovechar la eficacia del procesamiento en red en situaciones en las que la Carpeta de inspección es menos eficaz (y más difícil de configurar). Consulte “Examples” en la página 174 para ver ejemplos de lo que pueden hacer las secuencias de comandos. Si acaba de iniciarse en la creación de secuencias de comandos, consulte Adobe: Introducción a las secuencias de comandos, donde se presentan los conceptos básicos de las secuencias de comandos y se describen distintos lenguajes de secuencias de comandos disponibles, incluido JavaScript. JavaScript y otros lenguajes de secuencias de comandos funcionan en torno a los objetos y este manual también describe los conceptos básicos de la programación basada en objetos y modelos de objetos de documento. Aunque no tenga intención de aprender el lenguaje JavaScript, puede aprovechar de todos modos la eficacia de las secuencias de comandos mediante soluciones de terceros como Rush Network Render Queue, una interfaz de usuario gráfica que permite configurar procesos distribuidos desde cualquier equipo de la red sin tener que configurarlos en equipos individuales. También puede aprovechar la contribución de usuarios que comparten secuencias de comandos con otros usuarios. Los grandes estudios pueden tener a estos usuarios en plantilla, mientras que otros usuarios pueden visitar foros como los que encontrará en w w w.a dobefor u ms .com .

Acerca de esta guía Esta guía está destinada a usuarios que administren canalizaciones de gráficos (que pueden incluir también otras aplicaciones de secuencias de comandos) y que deseen escribir secuencias de comandos para agregar funcionalidades personalizadas a After Effects. Esta funcionalidad también la ofrecen soluciones de administración de procesos en red de terceros. Estos productos incluyen software diseñado para facilitar la administración de este proceso, por lo que es posible aprovechar la funcionalidad sin necesidad de editar manualmente las secuencias de comandos.

3

Introducción

Edición de secuencias de comandos

4

El núcleo de una aplicación de secuencias de comandos es el modelo de objetos. Cuando utiliza Adobe After Effects, crea proyectos, composiciones y elementos de la cola de procesamiento junto con todos los elementos que contienen: material de archivo, imágenes, sólidos, capas, máscaras, efectos y propiedades. En términos de secuencias de comandos, cada uno de estos elementos es un objeto. Esta guía describe los objetos JavaScript definidos para los proyectos de After Effects. Las secuencias de comandos reproducen gran parte de lo que se puede hacer mediante la interfaz de usuario de After Effects, por lo que es fundamental tener un sólido conocimiento de la aplicación para saber cómo utilizar esta funcionalidad. El modelo de objetos de After Effects está formado por un proyecto, elementos, composiciones, capas y elementos de la cola de procesamiento. Cada objeto tiene sus atributos especiales y cada objeto de un proyecto de After Effects tiene una identidad propia (aunque no todos se pueden utilizar con secuencias de comandos). Debería estar familiarizado con el modelo de objetos de After Effects para poder crear secuencias de comandos. Las secuencias de comandos de After Effects están basadas en ECMAScript (o más concretamente, en la tercera edición de la norma ECMA-262). Encontrará más documentación sobre esta norma en www.ecmainternational.org. Para aprovechar al máximo las posibilidades de las secuencias de comandos, necesitará además conocimientos sobre cómo se escriben en el nivel de sistema (para la integración con AppleScript o la línea de comandos Terminal en Mac OS y las secuencias de comandos de la línea de comandos en los equipos Windows), así como tener nociones básicas sobre cómo trabajar con JavaScript. NOTA: Los objetos de JavaScript llamados normalmente “propiedades” reciben el nombre de “atributos” en esta guía para evitar la confusión con la propia definición de una propiedad en After Effects (un valor que se puede animar de un efecto, máscara o transformación en una capa individual).

Expresiones Aunque las expresiones de After Effects y la interfaz de secuencias de comandos de After Effects emplean JavaScript y tienen acceso a propiedades de capas individuales, son entidades absolutamente distintas. Las expresiones no pueden acceder a información de las secuencias de comandos (como variables y funciones), a pesar de que se puede escribir una secuencia de comandos para crear o editar una expresión. Dado que tanto las expresiones como las secuencias de comandos emplean JavaScript, estar familiarizado con uno de estos conceptos puede ayudar a comprender el otro.

Matemática del movimiento La matemática del movimiento ya no se incluye en After Effects; su funcionalidad ha sido reemplazada por las secuencias de comandos y las expresiones. Todos los operadores matemáticos y lógicos comunes para ECMAScript están disponibles en las secuencias de comandos. Por ejemplo, con expresiones se puede simular la física de una pelota que bota mediante la aplicación de reglas matemáticas a una capa “pelota”. Pero con secuencias de comandos, se puede crear una interfaz de usuario completa que permita la animación de una capa de una pelota que bota y su sombra utilizando los criterios que especifica el usuario.

Edición de secuencias de comandos After Effects incluye un editor de JavaScript. Para iniciarlo, elija Archivo > Scripts > Abrir el Editor de secuencias de comandos. Este depurador y editor de secuencias de comandos, llamado Kit de herramientas de ExtendScript, proporciona una cómoda interfaz para crear y probar sus propias secuencias de comandos. Puede utilizar cualquier editor de texto para crear, editar y guardar secuencias de comandos, pero se recomienda que elija una aplicación que no agregue automáticamente información de encabezado al guardar los archivos y que guarde con la codificación Unicode (UTF-8).

4

Introducción

Activación de funciones de secuencias de comandos completas

5

• Algunas aplicaciones de Windows útiles para editar secuencias de comandos son EM Editor o el Bloc de

notas integrado (asegúrese de definir la codificación como UTF-8 en las opciones de guardar). • Entre las aplicaciones de Mac OS útiles para editar secuencias de comandos se incluyen BBEdit o la

aplicación integrada OS X TextEdit (asegúrese de definir el tipo de almacenamiento como Unicode [UTF-8] en las preferencias).

Formato JSX de ExtendScript After Effects admite ExtendScript, la implementación extendida de JavaScript de Adobe. Todas las aplicaciones de Adobe que proporcionan una interfaz de secuencias de comandos utilizan ExtendScript. Además de implementar el lenguaje JavaScript según las especificaciones ECMA 262 y E4X ECMA 357, ExtendScript ofrece algunas funciones y utilidades adicionales: Kit de herramientas de ExtendScript: Como ayuda para crear, depurar y probar secuencias de comandos,

ExtendScript proporciona un entorno de desarrollo y de prueba interactivo, el Kit de herramientas de ExtendScript. También define un objeto de depuración global, el objeto de dólar ($) y una utilidad de generación de informes para elementos de ExtendScript, la interfaz ExtendScript Reflection. Objetos File y Folder: Puesto que la sintaxis de los nombres de rutas es muy diferente en los distintos sistemas

operativos, Adobe ExtendScript define los objetos Archivo y Ca r p et a para proporcionar un acceso independiente de la plataforma al sistema de archivos subyacente. Módulo de interfaz de usuario ScriptUI: El módulo ScriptUI de ExtendScript permite crear e interactuar con

elementos de la interfaz de usuario. ScriptUI proporciona un modelo de objetos para ventanas y elementos de control de UI que se pueden emplear para crear una interfaz de usuario para las secuencias de comandos. Herramientas y utilidades: Además, ExtendScript ofrece herramientas y funciones, como una utilidad de

traducción que proporciona valores de cadenas de la interfaz de usuario en distintos idiomas y funciones globales para mostrar mensajes cortos en cuadros de diálogo (aler t , con f i r m y promp t ). Comunicación entre aplicaciones: ExtendScript proporciona un entorno de secuencias de comandos común para todas las aplicaciones de Adobe y permite la comunicación entre aplicaciones mediante secuencias de comandos. Comunicación externa: ExtendScript ofrece un objeto S o c ke t que permite la comunicación con equipos remotos desde las secuencias de comandos de After Effects.

Éstas y otras funciones se describen en detalle en Guía de herramientas de JavaScript, disponible con After Effects y en http://www.adobe.com/es/devnet/. Los archivos de secuencias de comandos de ExtendScript se diferencian por la extensión . js x , una variación de la extensión estándar . js utilizada con los archivos de JavaScript. Las secuencias de comandos de After Effects deben incluir la extensión de archivo .j sx para que la aplicación las reconozca correctamente. Cualquier archivo de texto codificado con UTF-8 que tenga la extensión .j sx se reconocerá como un archivo de ExtendScript. Se puede utilizar el kit de herramientas de ExtendScript Toolkit para exportar una versión binaria de un archivo de ExtendScript, cuya extensión es .js x bin . Es probable que los archivos binarios no puedan utilizarse con todas las funciones de integración de secuencias de comandos en After Effects.

Activación de funciones de secuencias de comandos completas Por motivos de seguridad, las funciones de secuencias de comandos que se ejecutan fuera de la aplicación After Effects (como agregar y eliminar archivos y carpetas en volúmenes, o el acceso a la red) están deshabilitadas de forma predeterminada. Para habilitar estas funciones, elija Preferencias > General y seleccione “Permitir que los scripts puedan escribir archivos y acceder a la red”. Lo cual le permite:

5

Introducción

Acceso y escritura de secuencias de comandos

6

• Escribir archivos • Crear carpetas y definir la carpeta actual • Crear una conexión socket (si desea información sobre esta utilidad de JavaScript, consulte Guía de

herramientas de JavaScript) Adobe proporciona un completo depurador de JavaScript, denominado Kit de herramientas de ExtendScript. El Kit de herramientas está deshabilitado de manera predeterminada con el fin de que los usuarios ocasionales no lo encuentren. Al editar o escribir secuencias de comandos, el Kit de herramientas ayuda a diagnosticar más rápidamente problemas relativos a secuencias de comandos. Para activar el kit de herramientas en el equipo local cuando se produzca un error de una secuencia de comandos, elija Preferencias > General y seleccione Activar el depurador de JavaScript. Si desea obtener información detallada sobre el Kit de herramientas de ExtendScript, consulte Guía de herramientas de JavaScript. Tenga en cuenta que el kit de herramientas se inicia sólo cuando se ejecuta una secuencia de comandos, no con expresiones, aunque éstas también utilicen JavaScript.

Acceso y escritura de secuencias de comandos Para crear y editar secuencias de comandos para After Effects, puede utilizar el kit de herramientas de ExtendScript o una aplicación de edición de texto externa que permita crear archivos con la codificación de texto Unicode UTF-8. Tenga cuidado con aplicaciones como Microsoft Word, que de forma predeterminada agregan información de encabezado a los archivos; estas aplicaciones crean errores de línea 0 en las secuencias de comandos y provocan un fallo de ejecución. Una secuencia de comandos puede residir en cualquier lugar pero, para que se muestre en el menú Scripts, es necesario que se guarde en la carpeta Scripts, dentro de la carpeta de la aplicación After Effects. No hay un método integrado para grabar una serie de acciones en una secuencia de comandos en After Effects del modo en que se puede realizar en Adobe Photoshop®. Las secuencias de comandos se crean fuera de After Effects y se ejecutan dentro, o externamente mediante una línea de comandos, el kit de herramientas de ExtendScript o el software de administración de procesos de terceros.

Menú y carpeta Scripts Las secuencias de comandos de After Effects residen en la carpeta Scripts, dentro de la misma carpeta que el archivo de la aplicación After Effects. Cuando se inicia la aplicación, sólo las secuencias de comandos guardadas en esta carpeta Scripts se enumeran automáticamente en el menú Scripts, aunque los archivos de secuencias de comandos pueden residir en cualquier lugar. Para ejecutar una secuencia de comandos que no aparece en el menú Scripts, elija Archivo > Scripts > Ejecutar guión y seleccione la secuencia de comandos en el cuadro de diálogo Abrir. También puede enviar a After Effects una secuencia de comandos desde el Kit de herramientas de ExtendScript, la línea de comandos (en Windows) o AppleScript (en Mac OS). Para que se muestre en el cuadro de diálogo Abrir, la secuencia de comandos debe incluir la extensión de archivo .js x adecuada.

Carpetas Shutdown y Startup La carpeta Scripts contiene dos carpetas llamadas Startup y Shutdown. After Effects ejecuta automáticamente las secuencias de comandos guardadas en estas carpetas, en orden alfabético, al iniciar y cerrar la aplicación, respectivamente. En la carpeta Startup puede colocar las secuencias de comandos que desea que se ejecuten al iniciar la aplicación. Se ejecutarán después de que se inicialice la aplicación y todos los plugins estén cargados.

6

Introducción

Acceso y escritura de secuencias de comandos

7

Las secuencias de comandos comparten un entorno global, de manera que cualquier secuencia que se ejecute al inicio puede definir variables y funciones disponibles para todas las secuencias de comandos. En todos los casos, las variables y las funciones, una vez definidas mediante la ejecución de la secuencia de comandos que las contiene, continúan en las siguientes secuencias de comandos durante una sesión de After Effects específica. Cuando se cierra la aplicación, todas estas variables y funciones definidas globalmente se eliminan. Asegúrese de que asigna nombres únicos a las variables incluidas en secuencias, de manera que una secuencia de comandos no vuelva a asignar por equivocación variables globales destinadas a continuar durante toda una sesión. También se pueden agregar atributos a objetos existentes, como el objeto Application (consulte “Application object” en la página 19), para extender la aplicación a otras secuencias de comandos. Las secuencias de comandos guardadas en la carpeta Shutdown se ejecutan cuando se cierra la aplicación. Esto se produce después de cerrar el proyecto pero antes de que se cierre otra aplicación.

El menú Ventana y la carpeta Paneles ScriptUI Desde la carpeta Scripts, puede crear otra carpeta con el nombre Paneles ScriptUI. Utilice esta carpeta para las secuencias de comandos cuya interfaz de usuario aparezca en un panel nativo (en lugar de aparecer en una paleta flotante, un cuadro de diálogo o una ventana). La ventaja de un panel es que se puede acoplar a otros paneles, como en un Proyecto, una Composición o Controles de tiempo, y dar la sensación de una mayor integración en la aplicación. Al igual que en el caso de los paneles nativos, se accede a los paneles ScriptUI desde el menú Ventana. En lugar de crear un objeto de ventana y añadirle controles, una secuencia de comandos Paneles ScriptUI utiliza el objeto “this” que representa al panel. Por ejemplo, el código siguiente añade un botón a un panel: v ar my Pan e l = t hi s ; my Pan e l . a dd ( " b u t ton " , [ 1 0 , 1 0 , 1 0 0 , 3 0 ] , " To o l # 1" ) ; my Pan e l .s how ( );

Si la secuencia de comandos crea su propia interfaz de usuario en una función, no puede utilizar “this”, ya que se referirá a la función en sí, no al panel. En este caso, debería pasar el objeto “this” como un argumento de la función. Por ejemplo: f u n c t io n c re a teU I ( th i s O b j) { v ar my Pan e l = t hi s O b j ; my Pan e l . a dd ( " b u t ton " , [ 1 0 , 1 0 , 1 0 0 , 3 0 ] , " To o l # 1" ) ; re tur n my Pan el ; } v ar my To ol sPane l = c reateUI (t hi s) ; my To ol sPa n e l .sh ow () ;

No se puede utilizar el comando del menú Archivo > Scripts > Ejecutar guión para ejecutar una secuencia de comandos que haga referencia a “this”. Para que la secuencia de comandos funcione con un objeto de ventana (accesible desde el menú Archivo > Scripts) o desde un panel nativo (accesible desde el menú Ventanas), compruebe si “this” es un objeto panel. Por ejemplo: f u n c t io n c re a teU I ( th i s O b j) { v ar my Pan e l = ( t h i s O b j i n s t a n ce o f Pa n e l ) ? t h is O b j : n ew Wi n d ow ( " p a l e t te " , " My To o l s " , [100 , 10 0, 3 00, 3 00]); my Pan e l . a dd ( " b u t ton " , [ 1 0 , 1 0 , 1 0 0 , 3 0 ] , " To o l # 1" ) ; re tur n my Pan el ; } v ar my To ol sPane l = c reateUI (t hi s) ; my To ol sPa n e l .sh ow () ;

7

Introducción

Envío de secuencias de comandos a After Effects desde el sistema

8

Envío de secuencias de comandos a After Effects desde el sistema Si está familiarizado con la ejecución de secuencias de comandos desde la línea de comandos en Windows o mediante AppleScript, puede enviar una secuencia directamente a la aplicación After Effects abierta para que la aplicación ejecute automáticamente la secuencia de comandos.

Cómo incluir secuencias de comandos de After Effects en una línea de comandos (Windows) A continuación se indican algunos ejemplos de entradas de la línea de comandos de Windows que envían una secuencia de comandos de After Effects a la aplicación sin utilizar la interfaz de usuario de After Effects para ejecutarla. En el primer ejemplo, se copia y pega la secuencia de comandos de After Effects directamente en la línea de comandos y después se ejecuta. El texto de la secuencia aparecerá entre comillas después del comando a fter f x.exe -s : a fter f x.exe -s "aler t ("Ac aba de env i ar una a l er t a a Af ter Effe ct s")"

También puede especificar la ubicación del archivo JSX que se va a ejecutar. Por ejemplo: a ft er f x . e xe – r c : \ m is D o cu m e n to s \ S c r i p t s \ s u AE S c r ip t He re .j s x a fter f x .e xe - r " c :\ m is D o cu m e n tos \ S c r i p t s\ Nom b re de Sc r i p t con S p ace s .js x "

Cómo incluir secuencias de comandos de After Effects en AppleScript (Mac OS) A continuación se indican tres ejemplos de secuencias de comandos AppleScript que envían un archivo JSX existente que contiene una secuencia de comandos de After Effects a la aplicación sin utilizar la interfaz de usuario de After Effects para ejecutar dicha secuencia. En el primer ejemplo, se copia la secuencia de comandos de After Effects directamente en el Editor de secuencias de comandos y, a continuación, se ejecuta. El texto de la secuencia aparecerá entre comillas después del comando DoScript, de manera que deben omitirse las comillas internas de la secuencia con el carácter de escape de barra invertida, como se muestra a continuación: te l l app l icat ion "Adobe Af ter Ef fe ct s CS 3 " D oS c r ip t " al er t( \ " Ac ab a de env i a r un a al er t a a Af ter E f fe c t s \ ") " e n d te l l

También puede mostrar un cuadro de diálogo que pida la ubicación del archivo JSX que se va a ejecutar, de la siguiente manera: s et t heF i l e to ch o o se fi l e te l l app l icat ion "Adobe Af ter Ef fe ct s CS 3 " D oS c r ip t th eF i l e e n d te l l

Por último, esta secuencia de comandos es quizá la más útil cuando se trabaja directamente en la edición de una secuencia de comandos JSX y se desea enviarla a After Effects para probarla o ejecutarla. Para utilizarla de manera eficaz, debe especificar la aplicación que contiene el archivo JSX abierto (en este ejemplo, TextEdit); si no sabe el nombre exacto de la aplicación, escriba lo más parecido a “TextEdit” y AppleScript le pedirá que la busque. Basta con que resalte el texto de la secuencia que desea ejecutar y, a continuación, active este AppleScript: (* E s t a s e c u e n c i a d e com a n d o s env í a l a s el e cc i ón a c t ua l a Af ter E f fe c t s com o un a se c uen c i a d e com an dos. *)

8

Introducción

Prueba y solución de problemas

9

te l l app l icat ion “ TextEd i t” s e t t h e _ s c r i p t to s e l e c t i o n as text e n d te l l te l l app l icat ion "Adobe Af ter Ef fe ct s CS 3 " a c t iva te D o S c r ip t th e _ s c r i p t e n d te l l

Si desea obtener más información sobre el uso de AppleScript, consulte los manuales AppleScript: the Definitive Guide de Matt Neuberg (O’Reilly & Associates) o AppleScript 1-2-3 de Sal Soghoian (Peachpit Press).

Prueba y solución de problemas Cualquier secuencia de comandos de After Effects que contenga un error que impida que se complete genera un mensaje de error en la aplicación. Este mensaje de error contiene información sobre la naturaleza del error y la línea de la secuencia de comandos en la que se ha producido. Además, After Effects incluye un depurador de JavaScript. Para obtener información adicional sobre cómo activar y utilizar el depurador, consulte la documentación del Kit de herramientas de ExtendScript en la Guía de herramientas de JavaScript.

Más recursos para aprender a utilizar secuencias de comandos Existen muchos recursos para aprender más sobre las secuencias de comandos que utilizan la norma ECMA. El motor de secuencias de comandos de After Effects admite la tercera edición de la norma ECMA-262, incluidos las convenciones léxicas y de anotación, tipos, objetos, expresiones e instrucciones. Para obtener una lista completa de las palabras clave y los operadores que se incluyen con ECMAScript, consulte el archivo ECMA-262.pdf, disponible en www.ecma-international.org/publications/standards/ Ecma-262.htm. Los libros relativos a JavaScript 1.2 también resultan útiles para entender cómo funcionan las secuencias de comandos en After Effects. Un libro que los usuarios de JavaScript reconocen como norma es JavaScript: The Definitive Guide, de David Flanagan (O’Reilly). Otra fuente de consulta considerable es JavaScript: A Beginner’s Guide de John Pollock (Osborne). Ambos contienen información relativa únicamente a las extensiones de JavaScript para exploradores de Internet; no obstante, también describen de forma detallada los conceptos básicos de las secuencias de comandos. También hay libros sobre cómo usar AppleScript y cómo crear secuencias de comandos desde la línea de comandos de Windows, y ambas se pueden utilizar para enviar secuencias a After Effects.

Variables de JavaScript Las secuencias de comandos comparten un entorno global, de manera que cualquier secuencia que se ejecute al inicio puede definir variables y funciones disponibles para todas las secuencias de comandos. En todos los casos, las variables y las funciones, una vez definidas mediante la ejecución de la secuencia de comandos que las contiene, continúan en las siguientes secuencias de comandos durante una sesión de After Effects específica. Cuando se cierra la aplicación, todas estas variables y funciones definidas globalmente se eliminan. Los creadores de secuencias de comandos deben tener precaución a la hora de asignar nombres únicos a las variables incluidas en secuencias, de manera que una secuencia de comandos no vuelva a asignar por equivocación variables globales destinadas a continuar durante toda una sesión.

9

Introducción

Más recursos para aprender a utilizar secuencias de comandos

10

Sintaxis de instrucciones y palabras clave de JavaScript Aunque no se puede proporcionar un recurso que describa de forma exhaustiva el uso de JavaScript, las siguientes tablas ofrecen una descripción general de las palabras clave, instrucciones, operadores, prioridad y asociatividad. En la siguiente tabla se enumeran y se describen todas las palabras clave e instrucciones que reconoce el motor de secuencias de comandos de After Effects.

Tabla 1

Sintaxis de instrucciones y palabras clave

Palabra clave/ instrucción

Descripción

b re a k

JavaScript estándar; cierra el bucle que se está ejecutando actualmente.

con t i nue

JavaScript estándar; interrumpe la ejecución de la repetición del bucle actual.

case

Etiqueta que se utiliza en una instrucción s w i tch .

def a ul t

Etiqueta que se utiliza en una instrucción s w i tch cuando no se encuentra una etiqueta c a s e .

do. ..w hile

Construcción estándar de JavaScript. Similar al bucle w hi l e , salvo que la evaluación de la condición del bucle se produce al final del mismo.

f al s e

Literal que representa el valor falso Booleano.

for

Construcción de bucle estándar de JavaScript.

for.. .i n

Construcción estándar de JavaScript. Proporciona una manera de desplazarse fácilmente por las propiedades de un objeto.

f u n c t io n

Se utiliza para definir una función.

i f / if . . . e ls e

Construcciones condicionales estándar de JavaScript.

new

Instrucción de constructor estándar de JavaScript.

nu l l

Se asigna a una variable, elemento de conjunto o propiedad de objeto para indicar que no contiene un valor válido.

re tur n

Forma estándar de JavaScript de devolver un valor de una función o salir de una función.

s w itch

Forma estándar de JavaScript de evaluar una expresión de JavaScript e intentar corresponder el valor de la expresión con una etiqueta ca s e .

t hi s

Método estándar de JavaScript para indicar el objeto actual.

t r ue

Literal que representa el valor verdadero Booleano.

un define d

Indica que todavía no se ha asignado un valor a la variable, elemento de conjunto o propiedad de objeto.

v ar

Sintaxis estándar de JavaScript que se utiliza para declarar una variable local.

w hi l e

Construcción estándar de JavaScript. Similar al bucle do... w hile , salvo que la evaluación de la condición del bucle se produce al principio del mismo.

w i th

Construcción estándar de JavaScript que se utiliza para especificar un objeto que se va a utilizar en instrucciones posteriores.

Operadores de JavaScript En las siguientes tablas se enumeran y se describen todos los operadores que reconoce el motor de secuencias de comandos de After Effects, y se indica la prioridad y la asociatividad de todos ellos.

10

Introducción

Más recursos para aprender a utilizar secuencias de comandos

11

Tabla 2

Descripción de los operadores

Operadores

Descripción

new

Asigna un objeto.

de l e te

Anula la asignación de un objeto.

t y p e of

Devuelve un tipo de datos.

voi d

Devuelve un valor sin definir.

.

Miembro de una estructura.

[]

Elemento de una matriz.

()

Llamada a una función.

++

Aumento anterior o posterior.

––

Reducción anterior o posterior.

–

Resta o negación unaria.

~

NOT bit a bit.

!

NOT lógico.

*

Multiplicar.

/

Dividir.

%

División modular.

+

Sumar.

>

Desplazamiento a la derecha bit a bit.

> >>

Desplazamiento a la derecha bit a bit sin signo.


=

Mayor o igual que.

==

Igual.

!=

Distinto.

&

AND bit a bit.

^

XOR bit a bit.

|

OR bit a bit.

&&

AND lógico.

||

OR lógico.

?:

Condicional (ternario).

=

Asignación.

+=

Asignación con operación de suma.

11

Introducción

Más recursos para aprender a utilizar secuencias de comandos

12

Operadores

Descripción

–=

Asignación con operación de resta.

*=

Asignación con operación de multiplicación.

/=

Asignación con operación de división.

%=

Asignación con operación de división modular.

< >=

Asignación con operación de desplazamiento a la derecha bit a bit.

> >> =

Asignación con operación de desplazamiento a la derecha bit a bit sin signo.

&=

Asignación con operación AND bit a bit.

^=

Asignación con operación XOR bit a bit.

|=

Asignación con operación OR bit a bit.

,

Evaluación múltiple.

Tabla 3

Prioridad de los operadores

Operadores (de mayor a menor prioridad)

Asociatividad

[ ], () , .

izquierda a derecha

new, dele te , – ( n eg a c i ón un a r i a ), !, t y p e of, void , + +, – –

derecha a izquierda

*, /, %

izquierda a derecha

+ , – ( re st a)

izquierda a derecha

< > , > >>

izquierda a derecha

< , < =, > , > =

izquierda a derecha

= =, !=

izquierda a derecha

&

izquierda a derecha

^

izquierda a derecha

|

izquierda a derecha

&&

izquierda a derecha

||

izquierda a derecha

?:

derecha a izquierda

= , /= , % =, > =, > > >= , &=, ^= , |= , += , –= , *=

derecha a izquierda

,

izquierda a derecha

12

JavaScript Reference

This chapter lists and describes JavaScript classes, objects, methods, attributes, and global functions defined by After Effects. The After Effects scripting engine supports ExtendScript, Adobe’s extended version of JavaScript, which implements the 3rd Edition of the ECMA-262 Standard, including its notational and lexical conventions, types, objects, expressions and statements. For a complete listing of the keywords and operators included with ECMAScript, refer to E C M A- 2 6 2 .p d f , available at www.ecma-international.org/publications/standards/Ecma262.htm. For an overview of the most common keywords and statements available from ECMA-262, see “JavaScript keywords and statement syntax” on page 10.

The After Effects Object Model As you look through this reference section, which is organized alphabetically by object, you can refer to the following diagrams for an overview of where the various objects fall within the hierarchy, and their correspondence to the user interface. SYSTEM

APPLICATION

SETTINGS

FOLDER

SOCKET

ITEMS MAYBEANYOFTHEFOLLOWINGTYPESOFITEM

PROJECT COMP)TEM

RENDER1UEUE

FILE

/2

/2

FOOTAGE)TEM

FOLDER)TEM

ITEMS LAYERS

ITEMS PROXY3OURCE

RENDER1UEUE)TEMS PROPERTIES

MAIN3OURCE

PROXY3OURCE

MAIN3OURCEPROXY3OURCE MAYBEANYOFTHEFOLLOWINGTYPESOFITEM

OUTPUT-ODULES SOLID3OURCE

/2

PLACEHOLDER3OURCE

COLOR

/2

FILE3OURCE

FILE

Hierarchy diagram of the main After Effects scripting objects

Note that the File, Folder, and Socket objects are defined by ExtendScript, and are documented in the JavaScript Tools Guide. ExtendScript also defines the ScriptUI module, a set of window and user-interface control objects, which are available to After Effects scripts. These are also documented in the JavaScript Tools Guide. The hierarchy of objects in scripting corresponds to the hierarchy in the user interface.

13

JavaScript Reference

The After Effects Object Model

14

The application contains a Project panel, which displays a project. The project contains compositions, which contain layers. The source for a layer can be a footage file, placeholder, or solid, also listed in the Project panel. Each layer contains settings known as properties, and these can contain markers and keyframes. The render queue contains render-queue items as well as render settings and output modules. All of these entities are represented by objects in scripting. NOTE: To avoid ambiguity, this manual uses the term “attribute” to refer to JavaScript object properties, and the term “property” or “AE property” to refer to After-Effects layer properties.

Object summary The following table lists all objects alphabetically, with links to the documentation page for each. Object

Description

“Global functions” on page 16

Globally available functions that allow you to display text for script debugging purposes, and help convert time values between seconds and frames.

“Application object” on page 19

A single global object, available by its name (a pp ), that provides access to objects and application settings within the After Effects application.

“AVItem object” on page 32

Represents audio/visual files imported into After Effects.

“AVLayer object” on page 40

Represents those layers that contain AVItem objects (Comp layers, footage layers, solid layers, text layers, and sound layers).

“CameraLayer object” on page 51

Represents a camera layer within a composition.

“Collection object” on page 52

Associates a set of objects or values as a logical group and provides access to them by index.

“CompItem object” on page 53

Represents a composition, and allows you to manipulate it and get information about it.

14

JavaScript Reference

The After Effects Object Model

15

Object

Description

“FileSource object” on page 61

Describes footage that comes from a file.

“FolderItem object” on page 63

Represents a folder in the Project panel.

“FootageItem object” on page 65

Represents a footage item imported into a project, which appears in the Project panel.

“FootageSource object” on page 68

Describes the file source of some footage.

“ImportOptions object” on page 74

Encapsulates options for importing files into After Effects.

“Item object” on page 77

Represents an item in a project that appears in the Project panel.

“ItemCollection object” on page 80

Collects items in a project.

“KeyframeEase object” on page 82

Encapsulates keyframe ease values in an After Effects property.

“Layer object” on page 84

A base class for layer classes.

“LayerCollection object” on page 93

Collects layers in a project.

“LightLayer object” on page 98

Represents a light layer within a composition.

“MarkerValue object” on page 99

Encapsulates marker values in an After Effects property.

“MaskPropertyGroup object” on page 103

Encapsulates mask attributes in a layer.

“OMCollection object” on page 105

Collects output modules in a render queue.

“OutputModule object” on page 106

Represents an output module for a render queue.

“PlaceholderSource object” on page 109 Describes a placeholder for footage. “Project object” on page 110

Represents an After Effects project.

“Property object” on page 119

Represents an After Effects property.

“PropertyBase object” on page 141

A base class for After Effects property and property group classes.

“PropertyGroup object” on page 148

Represents an After Effects property group.

“RenderQueue object” on page 153

Represents the After Effects render queue.

“RenderQueueItem object” on page 156

Represents a renderable item in a render queue.

“RenderQueueItem object” on page 156

Collects render-queue items in a render queue.

“RQItemCollection object” on page 162

Provides access to application settings and preferences.

“Shape object” on page 165

Encapsulates the outline shape information for a mask.

“ShapeLayer object” on page 168

Represents a shape layer within a composition.

“SolidSource object” on page 169

Describes a solid color that is the source of some footage.

“System object” on page 170

Provides access to the operating system from the application.

“TextDocument object” on page 172

Encapsulates the text in a text layer.

“TextLayer object” on page 173

Represents a text layer within a composition.

15

JavaScript Reference

Global functions

16

Global functions These globally available functions that are specific to After Effects. Any JavaScript object or function can call these functions, which allow you to display text in a small (3-line) area of the Info panel, and to convert numeric time values to and from string values. Global function

Description

cl e arO ut put ()

Clears text from the Info panel.

c u r re n t Fo r m a t To Ti m e ( )

Converts string time value to a numeric time value.

t i m eToCur ren t For m at ()

Converts a numeric time value to a string time value.

w r ite( )

Writes text to the Info panel, with no line break added.

w r ite L n ( )

Writes text to the Info panel, adding a line break at the end.

Additional global functions for standard user I/O (aler t , con fi r m , and prom pt ) and static functions for file I/O, are defined by ExtendScript; for detailed reference information, see the Adobe Bridge® JavaScript Reference. NOTE: The After Effects global functions for standard dialogs and file I/O are still supported in this release, but are deprecated and will not be supported in future releases. For details, see the After Effects 6.5 documentation.

clearOutput() global function cl e arO ut put () Description

Clears the output in the Info panel. Parameters

None. Returns

Nothing.

currentFormatToTime() global function c u r re n t Fo r m a t To Ti m e ( fo r m at te d Ti m e, f ps , is D ura t io n ) Description

Converts a formatted string for a frame time value to a number of seconds, given a specified frame rate. For example, if the formatted frame time value is 0:00:12 (the exact string format is determined by a project setting), and the frame rate is 24 fps, the time would be 0.5 seconds (12/24). If the frame rate is 30 fps, the time would be 0.4 seconds (12/30). If the time is a duration, the frames are counted from 0. Otherwise, the frames are counted from the project’s starting frame (see “Project displayStartFrame attribute” on page 112). Parameters for m at ted Tim e

The frame time value, a string specifying a number of frames in the project’s current time display format.

16

JavaScript Reference

Global functions

17

fps

The frames-per-second, a floating-point value.

i s D u r a ti o n

Optional. When true, the time is a duration (measured from frame 0). When false (the default), the time is measured from the project’s starting frame.

Returns

Floating-point value, the number of seconds.

timeToCurrentFormat() global function t i m eToCur ren t For m at (t im e , f p s , is D ura t i on ) Description

Converts a numeric time value (a number of seconds) to a frame time value; that is, a formatted string that shows which frame corresponds to that time, at the specified rate. For example, if the time is 0.5 seconds, and the frame rate is 24 fps, the frame would be 0:00:12 (when the project is set to Display Timecode). If the frame rate is 30 fps, the frame would be 0:00:15. The format of the timecode string is determined by a project setting. If the time is a duration, the frames are counted from 0. Otherwise, the frames are counted from the project’s starting frame (see “Project displayStartFrame attribute” on page 112). Parameters time

The number of seconds, a floating-point value.

fps

The frames-per-second, a floating-point value.

i s D u r a ti o n

Optional. When true, the time is a duration (measured from frame 0). When false (the default), the time is measured from the project’s starting frame.

Returns

String in the project’s current time display format.

write() global function w r ite( te x t ) Description

Writes output to the Info panel, with no line break added. Parameters tex t

The string to display. Truncated if too long for the Info panel.

Returns

Nothing. Example w r ite ( " T h i s text ap p e a r s i n In fo p a n e l " ) ; w r ite ( " w it h m o re o n s a m e l i n e . " ) ;

17

JavaScript Reference

Global functions

18

writeLn() global function w r ite L n ( t e x t) Description

Writes output to the Info panel and adds a line break at the end. Parameters tex t

The string to display.

Returns

Nothing. Example w r ite l n ( " T h is tex t a pp e ars on f i r s t l i n e " ) ; w r ite l n ( " T h is tex t a pp e ars on s e con d l i n e " );

18

JavaScript Reference

Application object

19

Application object a pp Description

Provides access to objects and application settings within the After Effects application. The single global object is always available by its name, a pp . Attributes of the Application object provide access to specific objects within After Effects. Methods of the Application object can create a project, open an existing project, control Watch Folder mode, purge memory, and quit the After Effects application. When the After Effects application quits, it closes the open project, prompting the user to save or discard changes as necessary, and creates a project file as necessary. Attributes Attribute

Reference

Description

proj ec t

“Application project attribute” on page 28 and “Project object” on page 110

The current After Effects project.

language

“Application language attribute” on page 24

The language in which the application is running.

vers i on

“Application version attribute” on page 30

The version number of the After Effects application.

b u i l dNa m e

“Application buildName attribute” on page 21

The name of this build of the application.

b u i l dNu m b e r

“Application buildNumber attribute” on The number of this build of the application. page 22

i s Wa tch Fo l der

“Application isWatchFolder attribute” on page 24

When true, the local application is running in Watch Folder mode.

i s Ren d e r E n g i n e

“Application isRenderEngine attribute” on page 24

When true, the local After Effects application is running as a render engine.

s e tt i n g s

“Application settings attribute” on page 30 and “RQItemCollection object” on page 162

Application settings that can be set via scripting.

o n E r ror

“Application onError attribute” on page 26

A callback function that is called when an error occurs in the application.

e x i t Cod e

“Application exitCode attribute” on page 24

A numeric status code used when executing a script externally (that is, from a command line or AppleScript). 0 if no error occurred. A positive number indicates an error that occurred while running the script.

e xi t Af ter L a u n ch A n d Eva l

“Application exitAfterLaunchAndEval attribute” on page 23

When true, the application remains open after running a script from the command line on Windows.

s avePro je c t On Cr as h

“Application saveProjectOnCrash attribute” on page 28

When true, the project is saved if the application closes unexpectedly.

m e m o r y In Us e

“Application memoryInUse attribute” on Memory in use by this application. page 25

19

JavaScript Reference

Application object

20

Methods Method

Reference

Description

newPro jec t ()

“Application newProject() method” on page 25

Creates a new project in After Effects.

open()

“Application open() method” on page 26

Opens a project or an Open Project dialog box.

qui t ()

“Application quit() method” on page 28

Quits the application.

w atch Fo l der ( )

“Application watchFolder() method” on page 30

Starts Watch Folder mode; does not return until Watch Folder mode is turned off.

p au se Wa tchFol de r ()

“Application pauseWatchFolder() method” on page 27

Pauses a current watch-folder process.

endWatch Folder()

“Application endWatchFolder() method” on Ends a current watch-folder process. page 23

p u r g e ()

“Application purge() method” on page 28

Purges a targeted type of cached information (replicates Purge options in the Edit menu).

b eg i nUndoGroup()

“Application beginUndoGroup() method” on page 21

Groups the actions that follow it into a single undoable step.

endUndoGroup()

“Application endUndoGroup() method” on page 22

Ends an undo group; needed only when a script contains more than one undo group.

b eg i nSup pres sD i al o g s( )

“Application beginSuppressDialogs() method” on page 21

Begins suppression of dialogs in the user interface.

e n d Su p p re s s D i a l o g s( )

“Application endSuppressDialogs() method” on page 22

Ends suppression of dialogs in the user interface.

s e tMemor yUsa geLi mi ts ()

“Application setMemoryUsageLimits() method” on page 29

Sets memory usage limits as in the Memory & Cache preferences area.

s e tS ave Preferen ces O n Qu it ( )

“Application setSavePreferencesOnQuit() method” on page 29

Sets whether preferences are saved when the application is quit.

a c t iva te( )

“Application activate() method” on page 20 Brings the After Effects main window to the front of the screen.

s ch e dul e Tas k( )

“Application scheduleTask() method” on page 29

Schedules a JavaScript script for delayed execution.

c a n ce l Tas k( )

“Application cancelTask() method” on page 22

Cancels a scheduled task.

p a r s e Sw a tch F i l e ( )

“Application parseSwatchFile() method” on Loads a color swatch from an Adobe Swatch page 27 Exchange (ASE) file.

Application activate() method a pp. ac t iv ate () Description

Opens the application main window if it is minimized or iconified, and brings it to the front of the desktop. Parameters

None.

20

JavaScript Reference

Application object

21

Returns

Nothing.

Application beginSuppressDialogs() method a pp. b e g i n Su pp re s s D ia l o g s () Description

Begins suppression of script error dialog boxes in the user interface. Use en dSuppres s D ia l og s () to resume the display of error dialogs. See “Application endSuppressDialogs() method” on page 22. Parameters

None. Returns

Nothing.

Application beginUndoGroup() method a p p. b e g i n Un d o Grou p( u n d oSt r in g ) Description

Marks the beginning of an undo group, which allows a script to logically group all of its actions as a single undoable action (for use with the Edit > Undo/Redo menu items). Use the endUndoGrou p() method to mark the end of the group. (See “Application endUndoGroup() method” on page 22.) b eg i nUndoGroup() and endUn doGrou p() pairs can be nested. Groups within groups become part of the larger group, and will undo correctly. In this case, the names of inner groups are ignored. Parameters u n d o S t r in g

The text that will appear for the Undo command in the Edit menu (that is, “Undo < un do St r i n g > ”)

Returns

Nothing.

Application buildName attribute a pp. bu il d Nam e Description

The name of the build of After Effects being run, used internally by Adobe for testing and troubleshooting. Type

String; read-only.

21

JavaScript Reference

Application object

22

Application buildNumber attribute a pp. bu il d Num b er Description

The number of the build of After Effects being run, used internally by Adobe for testing and troubleshooting. Type

Integer; read-only.

Application cancelTask() method a pp. c an cel Ta sk ( t a s k I D) Description

Removes the specified task from the queue of tasks scheduled for delayed execution. Parameters t as kI D

An integer that identifies the task, as returned by ap p.s ch e du l e Tas k () .

Returns

Nothing.

Application endSuppressDialogs() method a pp. e n dSu pp re ss D ia l o g s ( ale r t ) Description

Ends the suppression of script error dialog boxes in the user interface. Error dialogs are displayed by default; call this method only if b eg i nSu ppres sD i al o g s( ) has previously been called. See “Application beginSuppressDialogs() method” on page 21. Parameters a l er t

Boolean; when true, errors that have occurred following the call to b e g i nSup pres sD i al o g s( ) are displayed in a dialog box.

Returns

Nothing.

Application endUndoGroup() method a pp. en dUn doGrou p( ) Description

Marks the end of an undo group begun with the app.be g i nUndoGro up() method. You can use this method to place an end to an undo group in the middle of a script, should you wish to use more than one undo group for a single script. If you are using only a single undo group for a given script, you do not need to use this method; in its absence at the end of a script, the system will close the undo group automatically.

22

JavaScript Reference

Application object

23

Calling this method without having set a b e g i n Un d o Grou p ( ) method yields an error. Parameters

None. Returns

Nothing.

Application endWatchFolder() method a pp. en dWa tchFol der( ) Description

Ends Watch Folder mode. Parameters

None Returns

Nothing. See also

“Application watchFolder() method” on page 30 “Application parseSwatchFile() method” on page 27 “Application isWatchFolder attribute” on page 24

Application exitAfterLaunchAndEval attribute a pp. exitAfter L aun chAnd Ev al Description

This attribute is used only when executing a script from a command line on Windows. When the application is launched from the command line, the – r or – s command line flag causes the application to run a script (from a file or from a string, respectively). If this attribute is set to true, After Effects will exit after the script is run; if it is false, the application will remain open. This attribute only has an effect when After Effects is run from the Windows command line. It has no effect in Mac OS. Type

Boolean; read/write.

23

JavaScript Reference

Application object

24

Application exitCode attribute a pp. ex i tCo de Description

A numeric status code used when executing a script externally (that is, from a command line or AppleScript). • In Windows, the value is returned on the command line when After Effects was launched on the commands

line (using the af ter f x or a f ter fx – m command), and a script was specified with the – r or – s option. • in Mac OS, the value is returned as the AppleScript D oS c r i p t result for each script.

In both Mac OS and Windows, the value is set to 0 (E X I T _ S U C C E S S ) at the beginning of each script evaluation. In the event of an error while the script is running, the script can set this to a positive integer that indicates what error occurred. Type

Integer; read/write. Example a pp. ex i tCo de = 2 ; / / on qui t, i f v a lue is 2, a n er ror ha s o ccu r re d

Application isRenderEngine attribute a p p. is Ren d er E n g in e Description

True if After Effects is running as a render engine. Type

Boolean; read-only.

Application isWatchFolder attribute a pp. is WatchFol der Description

True if the Watch Folder dialog box is currently displayed and the application is currently watching a folder for rendering. Type

Boolean; read-only.

Application language attribute a pp. l an g u ag e Description

The language After Effects is running.

24

JavaScript Reference

Application object

25

Type

A L a n gu ag e enumerated value; read-only. One of: L a n g u a ge . E N G L I S H L a n g u a ge . F R E N C H L a n g u a ge . G E R M AN L a n g u a ge . I TAL I A N L a n g u a ge . JA PA N E S E L a n g u a ge . S PAN I S H Example v ar l a n g = a pp. l a n g u ag e ; if (lang == Language.ENGLISH) a l er t( " Af te r E ff e c ts i s r u n n i n g i n E n g l i sh . " ) ; e l s e if ( l a n g = = L a n g u a g e . F R E N C H ) a l er t ( " Af te r E ff e c ts i s r u n n i n g i n Fren ch. " ) ; e l se a l er t ( " Af te r E ff e c ts i s n o t r u n n in g in E n g l is h o r Fre n ch . " ) ;

Application memoryInUse attribute a p p. m e m o r yIn Use Description

The number of bytes of memory currently used by this application. Type

Number; read-only.

Application newProject() method a pp. n ew Proje c t( ) Description

Creates a new project in After Effects, replicating the File > New > New Project menu command. If the current project has been edited, the user is prompted to save it. If the user cancels out of the Save dialog box, the new project is not created and the method returns null. Use a pp.pro je c t .c lo se (C l os eO p t i o n s. D O_ N OT _ S AVE _ C H A N G E S ) to close the current project before opening a new one. See “Project close() method” on page 112. Parameters

None. Returns

A new Project object, or null if no new project is created. Example a pp. pro je c t .cl o se( C l os eO p t i on s. D O _ N OT _ S AV E _ C H AN G E S ); a pp. n ew Proje c t( );

25

JavaScript Reference

Application object

26

Application onError attribute a pp. on E r ror Description

The name of a callback function that is called when an error occurs. By creating a function and assigning it to this attribute, you can respond to errors systematically; for example, you can close and restart the application, noting the error in a log file if it occurred during rendering. See “RenderQueue render() method” on page 154. The callback function is passed the error string and a severity string. It should not return any value. Type

A function name string, or null if no function is assigned; read/write. Example f u n c t io n e r r ( e r r St r i n g ) { a l er t( er rS t r in g ); } a pp. on E r ror = er r ;

Application open() method a pp. op en () a pp. op en (f i l e) Description

Opens a project. Parameters file

Optional. An ExtendScript File object for the project file to open. If not supplied, the method prompts the user to select a project file.

Returns

A new Project object for the specified project, or null if the user cancels the Open dialog box. Example v ar my _file = new File (". ./my_folder/my_test .a ep"); i f (my _ fi l e . ex i st s) { n e w _ p ro j e c t = a p p.o p e n ( my _ f i l e ) ; i f (n e w _ proj e c t) { a l er t( new _ proje c t.f i le.n ame) ; } }

26

JavaScript Reference

Application object

27

Application parseSwatchFile() method a pp. pa rse Sw atchF i l e( file ) Description

Loads color swatch data from an Adobe Swatch Exchange (ASE) file. Parameters file

The file specification, an ExtendScript F il e object.

Returns

The swatch data, in this format: d at a. m ajo r Ver si o n

The ASE version number.

d at a. m in or Vers ion d at a. v al u e s

An array of Swa tchVa lue .

Swa tchVa lue .t y p e

One of " RG B " , " C M Y K" , " LA B" , " Gr ay "

Swa tchVa lue .r

When t y p e = " RG B" , the color values in the range [0.0..1.0].

Swa tchVa lue .g

0, 0, 0 is Black.

Swa tchVa lue .b Swa tchVa lue .c

When t y p e = " C MY K " , the color values in the range [0.0..1.0].

Swa tchVa lue .m

0, 0, 0, 0 is White.

Swa tchVa lue .y Swa tchVa lue .k Swa tchVa lue .L

When t y p e = " L AB" , the color values.

Swa tchVa lue .a

L is in the range [0.0..1.0]. a and b are in the range [-128.0..+128.0]

Swa tchVa lue .b Swa tchVa lue .va lue

0, 0, 0 is Black. When t y p e = " Gr ay " , the va lue range is [0.0..1.0]. 0.0 is Black.

Application pauseWatchFolder() method a pp. pa useWatchFo lder( p au s e) Description

Pauses or resumes the search of the target watch folder for items to render. Parameters p au se

True to pause, false to resume.

Returns

Nothing.

27

JavaScript Reference

Application object

28

See also

“Application isWatchFolder attribute” on page 24 “Application watchFolder() method” on page 30 “Application endWatchFolder() method” on page 23

Application project attribute a pp. pro je c t Description

The project that is currently loaded. See “Project object” on page 110. Type

Project object; read-only.

Application purge() method a pp. pu rg e( tar ge t ) Description

Purges unused data of the specified types from memory. Replicates the Purge options in the Edit menu. Parameters t arg e t

The type of elements to purge from memory; a Pur g eTa rg et enumerated value, one of:

• Pur g e Ta r ge t . A L L _ C AC HE S : Purges all data that After Effects has cached to physical memory. • Purg e Tar ge t .UN D O _ C AC H E S : Purges all data saved in the undo cache. • Pur g e Tar ge t . S NA P S HOT _ C AC H E S : Purges all data cached as comp/layer snapshots. • Pur g e Ta r ge t . I M AG E _ C AC H E S : Purges all saved image data. Returns

Nothing.

Application quit() method a pp. qui t( ) Description

Quits the After Effects application. Parameters

None. Returns

Nothing.

Application saveProjectOnCrash attribute a pp. saveProj ec tO nCr a sh

28

JavaScript Reference

Application object

29

Description

When true (the default), After Effects attempts to display a dialog box that allows you to save the current project if an error causes the application to quit unexpectedly. Set to false to suppress this dialog box and quit without saving. Type

Boolean; read/write.

Application scheduleTask() method a pp. sch ed ul eTa sk ( st r in g To Ex e cut e, de lay, re p e at ) Description

Schedules the specified JavaScript for delayed execution. Parameters s t r i n g ToE xe c ute

A string containing JavaScript to be executed.

de l ay

A number of milliseconds to wait before executing the JavaScript. A floating-point value.

rep e at

When true, execute the script repeatedly, with the specified delay between each execution. When false the script is executed only once.

Returns

Integer, a unique identifier for this task, which can be used to cancel it with ap p.ca nce l Ta sk () .

Application setMemoryUsageLimits() method a pp. se t Mem o r y Us ag eL im i t s( im a geC a c he Pe rc e n t a ge, m ax imu m Me m o r y Pe rce n t age ) Description

Sets memory usage limits as in the Memory & Cache preferences area. For both values, if installed RAM is less than a given amount (n gigabytes), the value is a percentage of the installed RAM, and is otherwise a percentage of n. The value of n is: 2 GB for 32-bit Windows, 4 GB for 64-bit Windows, 3.5 GB for Mac OS. Parameters i m a ge Ca chePercen ta g e

Floating-point value, the percentage of memory assigned to image cache.

m a x im u m Me m o r y Pe rcen t a ge

Floating-point value, the maximum usable percentage of memory.

Returns

Nothing.

Application setSavePreferencesOnQuit() method a pp. se t S avePref eren ces On Q ui t (d oS av e) Description

Set or clears the flag that determines whether preferences are saved when the application is closed.

29

JavaScript Reference

Application object

30

Parameters doS ave

When true, preferences saved on quit, when false they are not.

Returns

Nothing.

Application settings attribute a pp. se t ti n g s Description

The currently loaded settings. See “Settings object” on page 163. Type

Settings object; read-only.

Application version attribute a pp. versi on Description

An alphanumeric string indicating which version of After Effects is running. Type

String; read-only. Example v ar ver = a p p. vers i o n ; a l er t( " T h i s m a chi n e is r un n in g versi o n " + ver + " o f Af ter E f fe c t s . " ) ;

Application watchFolder() method a pp. wa tchFol der( f o l d e r_ o b j e c t _t o _ w a t c h) Description

Starts a Watch Folder (network rendering) process pointed at a specified folder. Parameters fo l de r _ o b j e c t _ to _ wa tch

The ExtendScript Folder object for the folder to watch.

Returns

Nothing. Example v ar t heFolder = new Folder(“c: /too l”); a pp. wa tchFolder(theFolder);

30

JavaScript Reference

Application object

31

See also

“Application endWatchFolder() method” on page 23 “Application parseSwatchFile() method” on page 27 “Application isWatchFolder attribute” on page 24

31

JavaScript Reference

AVItem object

32

AVItem object a pp. pro je c t .i tem ( i n d e x) 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” on page 77. • 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” on page 53 and “FootageItem object” on page 65. Attributes Attribute

Reference

Description

name

“AVItem name attribute” on page 35

The name of the object as shown in the Project panel.

w i dt h

“AVItem width attribute” on page 38

The width of the item.

h eig h t

“AVItem height attribute” on page 34

The height of the item.

p i xel As p e c t

“AVItem pixelAspect attribute” on page 35

The pixel aspect ratio of the item.

f r a m eRa te

“AVItem frameRate attribute” on page 34

The frame rate of the item.

f r a m eD ur a t i on

“AVItem frameDuration attribute” on page 33 The frame duration for the item.

du r at i on

“AVItem duration attribute” on page 33

The total duration of the item.

u s e Prox y

“AVItem useProxy attribute” on page 38

When true, a proxy source is used for this item.

prox y S ou rce

“AVItem proxySource attribute” on page 35

The FootageItem object used as proxy for the item.

time

“AVItem time attribute” on page 38

Current time of the item.

u s e dIn

“AVItem usedIn attribute” on page 38

The CompItem objects that use this item.

h as Vi de o

“AVItem hasVideo attribute” on page 34

When true, the item has a video component.

h as Au di o

“AVItem hasAudio attribute” on page 34

When true, the item has an audio component.

fo o t ag e M is s in g

“AVItem footageMissing attribute” on page 33

When true, the item cannot be found or is a placeholder.

Methods Method

Reference

Description

s e tProxy ( )

“AVItem setProxy() method” on page 36

Sets a proxy for the item.

s e tProxyWi thS e quence( )

“AVItem setProxyWithSequence() method” on page 37

Sets a sequence as a proxy for the item.

s e tProxyWi thS o lid ( )

“AVItem setProxyWithSolid() method” on page 37

Sets a solid as a proxy for the item.

s e tProxyWi thP l a ceh older( )

“AVItem setProxyWithPlaceholder() method” on Sets a placeholder as a proxy for the item. page 36

s e tProxy ToNon e ( )

“AVItem setProxyToNone() method” on page 36 Removes the proxy for the item.

32

JavaScript Reference

AVItem object

33

AVItem duration attribute a pp. pro je c t .i tem ( in d e x) .d u r a ti o n 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 d u r a ti o n of the composition, and is read/write. • In a FootageItem, the value is linked to the dur at i on of the m a i n S o u rce object, 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 attribute a pp. pro je c t .i tem ( in d e x) .fo o t ag e M is s i n g 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 m i s s in g Fo o ta g e Pat h 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.

AVItem frameDuration attribute a pp. pro je c t .i tem ( in d e x) .f r a m e D u r at i on Description

Returns the length of a frame for this AVItem, in seconds. This is the reciprocal of f r a m eRa te . When set, the reciprocal is automatically set as a new f r am e R a te value. This attribute returns the reciprocal of the f r am e R a te , 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 m a in S o u rce , and is read-only. To change it, set the con f o r m Fr a m e R a te of the m a i n S o u rce object. This sets both the f r a m e R ate and f r a m e D u r at i o n of the FootageItem. Type

Floating-point value in the range [1/99.. 1.0]; read-only for a FootageItem, otherwise read/write.

33

JavaScript Reference

AVItem object

34

AVItem frameRate attribute a pp. pro je c t .i tem ( in d e x) .f r a m eRa te Description

The frame rate of the AVItem, in frames-per-second. This is the reciprocal of the f r am e D u r a t ion . When set, the reciprocal is automatically set as a new f r am e D u r a t ion value. • In a CompItem, the value is linked to the f r a m eRa te of the composition, and is read/write. • In a FootageItem, the value is linked to the f r a m e R ate of the m a i n S o u rce object, and is read-only. To change

it, set the confor mFr ame Rate of the m a i n S o u rce object. This sets both the fr ameR ate and fr ame D ur a ti on of the FootageItem. Type

Floating-point value in the range [1.0..99.0]; read-only for a FootageItem, otherwise read/write.

AVItem hasAudio attribute a pp. pro je c t .i tem ( in d e x) .h as Au di o 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 m a i n S o u rce object. Type

Boolean; read-only.

AVItem hasVideo attribute a pp. pro je c t .i tem ( in d e x) .h as Vi de o Description

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 m a i n S o u rce object. Type

Boolean; read-only.

AVItem height attribute a pp. pro je c t .i tem ( in d e x) .h ei g h t Description

The height of the item in pixels. • In a CompItem, the value is linked to the composition, and is read/write.

34

JavaScript Reference

AVItem object

35

• In a FootageItem, the value is linked to the m a i n S o u rce object, and is read/write only if the m a i n S o u rce

object is a SolidSource. Otherwise, it is read-only. Type

Integer in the range [1...30000]; read/write, except as noted.

AVItem name attribute a pp. pro je c t .i tem ( in d e x) .n a m e Description

The name of the item, as shown in the Project panel. • In a FootageItem, the value is linked to the m a i n S o u rce object. If the m ai n S ource 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.

AVItem pixelAspect attribute a pp. pro je c t .i tem ( in d e x) .p i xel As p e c t Description

The pixel aspect ratio of the item. • In a CompItem, the value is linked to the composition. • In a FootageItem, the value is linked to the m a i n S o u rce object.

Certain p ixel As p e c t values are specially known to After Effects, and are stored and retrieved with perfect accuracy. These are the set {1 , 0.9 , 1.2 , 1.0 7, 1. 42, 2 , 0.9 5, 1. 9} . Other values may show slight rounding errors when you set or get them; that is, the value you retrieve after setting may be slightly different from the value you supplied. Type

Floating-point value, in the range [0.01..100.0]; read/write.

AVItem proxySource attribute a pp. pro je c t .i tem ( in d e x) .p roxy S o u rce 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: se t Prox y ( ) , s e tProxyWi thS e quence( ) , se t Prox y Wi t hS o l i d () , or s e t Proxy Wi thP l a ce h o l der ( ) . Type

FootageSource object; read-only.

35

JavaScript Reference

AVItem object

36

AVItem setProxy() method a pp. pro je c t .i tem ( in d e x) . s e tProxy ( 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 prox y S ource attribute, and sets u se Prox y 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 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.

AVItem setProxyToNone() method a pp. pro je c t .i tem ( in d e x) . s e tProxy To No n e () Description

Removes the proxy from this AVItem, sets the value of p roxy S o u rce to null, and sets the value of u se Prox y to f al s e . Parameters

None. Returns

Nothing.

AVItem setProxyWithPlaceholder() method a pp. pro je c t .i tem ( in d e x) .s e tProxy Wi th Pl a ceh ol der( n am e , w id t h , he ig h t , f ram e R at e, durat ion ) Description

Creates a PlaceholderSource object with specified values, sets this as the value of the prox y S ource attribute, and sets u s e Prox y to true. It does not preserve the interpretation parameters, instead using the user preferences. 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.

w i dt h, heig ht

The pixel dimensions of the placeholder, an integer in the range [4..30000].

f r a m eRa te

The frames-per-second, an integer in the range [1..99].

36

JavaScript Reference

AVItem object

37

The total length in seconds, up to 3 hours. An integer in the range [0.0..10800.0].

du r at i on Returns

Nothing.

AVItem setProxyWithSequence() method a pp. pro je c t .i tem ( in d e x) .se tProxyWith S equence( file, forc eAlphabe t ical ) 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 prox y S ource attribute, and sets u s e Prox y 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.

force Alp ha b e t ic a l

When true, use the “Force alphabetical order” option.

Returns

Nothing.

AVItem setProxyWithSolid() method a pp. pro je c t .i tem ( in d e x) .s e tProxyWith S olid ( c ol or, n am e , w id t h, he i g h t , p ix e lAsp ec t) Description

Creates a SolidSource object with specified values, sets this as the value of the prox y S ource attribute, and sets u s e Prox y 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 co lor

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.

w i dt h, heig ht

The pixel dimensions of the placeholder, an integer in the range [1...30000].

p i xel As p e c t

The pixel aspect of the solid, a floating-point value in the range [0.01... 100.0].

Returns

Nothing.

37

JavaScript Reference

AVItem object

38

AVItem time attribute a pp. pro je c t .i tem ( in d e x) .t i m e 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 t i m eTo Cur ren t Fo r m at to convert it to a string value that expresses the time in terms of frames; see “timeToCurrentFormat() global function” on page 17. It is an error to set this value for a FootageItem whose m a i n S o u rce is still (ite m .m ai n S ource .i s St i l l is true). Type

Floating-point value; read/write.

AVItem usedIn attribute a pp. pro je c t .i tem ( in d e x) .u se dIn 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 attribute a pp. pro je c t .i tem ( in d e x) .u seProx y Description

When true, a proxy is used for the item. It is set to true by all the S e t Prox y methods, and to false by the S e tProx y ToNon e( ) method. Type

Boolean; read/write.

AVItem width attribute a pp. pro je c t .i tem ( in d e x) .w i d th 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 m a i n S o u rce object, and is read/write only if the m a i n S o u rce

object is a SolidSource. Otherwise, it is read-only.

38

JavaScript Reference

AVItem object

39

Type

Integer in the range [1...30000]; read/write, except as noted.

39

JavaScript Reference

AVLayer object

40

AVLayer object a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ) Description

The AVLayer object provides an interface to those layers that contain AVItem objects (Comp layers, footage layers, solid layers, text layers, and sound layers). • AVLayer is a subclass of Layer. All methods and attributes of Layer, in addition to those listed below, are

available when working with AVLayer. See “Layer object” on page 84. • AVLayer is a base class for TextLayer, so AVLayer attributes and methods are available when working with

TextLayer objects. See “TextLayer object” on page 173. AE Properties

Different types of layers have different AE properties. AVLayer has the following properties and property groups: Ma r ker Tim e Remap Mot i on Tr a ckers Ma sk s Effects Tr an s for m Anchor Point Pos i t i on S c al e Orientation X Rot at i on Y Rot at i o n Rot at i o n O p a ci t y L ayer S t y l e s Ma ter i al O p t i on s C as ts S h a dow s L i g ht Tr a n s m i ss i on Acce p ts S h a dows Acce p ts L i g h ts Ambi ent D i ff us e S p e c u l ar Shininess Met al Aud i o Aud i o Le ve l s Example

If the first item in the project is a CompItem, and the first layer of that CompItem is an AVLayer, the following sets the layer qua l it y, s ta r t Ti m e , and i n Poi n t . v ar f i r s t L aye r = a p p. p ro je c t .i te m ( 1 ) . l ayer (1 ) ; first L ayer.qu alit y = L ayerQ ualit y.B EST; f i r s t L aye r. s t a r t Ti m e = 1 ;

40

JavaScript Reference

AVLayer object

41

f i r s t L aye r. i n Po i n t = 2 ; Attributes Attribute

Reference

Description

s o u rce

“AVLayer source attribute” on page 48

The source item for this layer.

i s Na m e Fro m S o u rce

“AVLayer isNameFromSource attribute” on page 47

When true, the layer has no expressly set name, but contains a named source.

h eig h t

“AVLayer height attribute” on page 47

The height of the layer.

w i dt h

“AVLayer width attribute” on page 50

The width of the layer.

a ud io E n ab l ed

“AVLayer audioEnabled attribute” on page 43

When true, the layer's audio is enabled.

mo tionBlu r

“AVLayer motionBlur attribute” on page 47

When true, the layer's motion blur is enabled.

e f fe c t sAc t ive

“AVLayer effectsActive attribute” on page 45

When true, the layer's effects are active.

adju st mentLayer

“AVLayer adjustmentLayer attribute” on page 42

When true, this is an adjustment layer.

g u id e L ayer

“AVLayer guideLayer attribute” on page 46

When true, this is a guide layer.

t hree DL ayer

“AVLayer threeDLayer attribute” on page 49

When true, this is a 3D layer.

t hree DPer Cha r

“AVLayer threeDPerChar attribute” on page 49

When true, 3D is set on a per-character basis in this text layer.

can S et Col l ap se Tr ans for ma tion

“AVLayer canSetCollapseTransformation When true, it is legal to change the value of attribute” on page 45 col l a ps e Tr a n sf or m a t i o n .

co l l ap s e Tr an s fo r m at i on

“AVLayer collapseTransformation attribute” on page 45

When true, collapse transformation is on.

f r a m e Bl e n di n g

“AVLayer frameBlending attribute” on page 46

When true, frame blending is enabled.

f r a m e Bl e n di n g Ty p e

“AVLayer frameBlendingType attribute” on page 46

The type of frame blending for the layer.

c a n S e t Ti m e Rem a p E n a bl e d

“AVLayer canSetTimeRemapEnabled attribute” on page 45

When true, it is legal to change the value of t i m e Rem a p E n a bl e d .

t i m eRem ap E n ab l e d

“AVLayer timeRemapEnabled attribute” on page 49

When true, time remapping is enabled on this layer.

h as Au di o

“AVLayer hasAudio attribute” on page 46

When true, the layer contains an audio component.

a ud io Ac t ive

“AVLayer audioActive attribute” on page 42

When true, the layer's audio is active at the current time.

b l endi ngMo de

“AVLayer blendingMode attribute” on page 43

The blending mode of the layer.

preser veTr a n spa rency

“AVLayer preserveTransparency attribute” on page 48

When true, preserve transparency is enabled.

t r ackMat teTy p e

“AVLayer trackMatteType attribute” on page 50

if layer has a track matte, specifies the way it is applied.

41

JavaScript Reference

AVLayer object

42

Attribute

Reference

Description

i s Tr a ck Ma tte

“AVLayer isTrackMatte attribute” on page 47

When true, this layer is being used as a track matte for the layer below it.

h as Tr a ck Ma tte

“AVLayer hasTrackMatte attribute” on page 46

When true, the layer above is being used as a track matte on this layer.

qu a l i t y

“AVLayer quality attribute” on page 48

The layer quality setting.

a utoO r i en t

“AVLayer autoOrient attribute” on page 43

The type of automatic orientation for the layer.

Methods Method

Reference

Description

a udio Ac t iveAtTime()

“AVLayer audioActiveAtTime() method” on page 43

Reports whether this layer's audio is active at a given time.

c al c u l ate Tr a n s for m From Poi n t s( )

“AVLayer calculateTransformFromPoints() method” on page 44

Calculates a transformation from a set of points in this layer.

rep l a c e S o u rce ( )

“AVLayer replaceSource() method” on page 48

Changes the source item for this layer.

s o u rce Rec t AtTi m e ( )

“AVLayer sourceRectAtTime() method” on page 49

Retrieves the source rectangle of a layer.

AVLayer adjustmentLayer attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ) . a d j u s t m e n t L ayer Description

True if the layer is an adjustment layer. Type

Boolean; read/write.

AVLayer audioActive attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). aud i oAc t ive Description

True if the layer's audio is active at the current time. For this value to be true, aud i oEna ble d must be true, no other layer with audio may be soloing unless this layer is soloed too, and the time must be between the in Poi n t and o utPoi n t of this layer. Type

Boolean; read-only.

42

JavaScript Reference

AVLayer object

43

AVLayer audioActiveAtTime() method a pp. pro je c t .i tem ( in d e x) .layer(i n de x ). aud i oAc t iveAt Ti m e (t im e ) Description

Returns true if this layer's audio will be active at the specified time. For this method to return true, a ud io E n ab l ed must be true, no other layer with audio may be soloing unless this layer is soloed too, and the time must be between the i n Poin t and outPoint of this layer. Parameters time

The time, in seconds. A floating-point value.

Returns

Boolean.

AVLayer audioEnabled attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). aud i oEna bl e d Description

When true, the layer's audio is enabled. This value corresponds to the audio toggle switch in the Timeline panel. Type

Boolean; read/write.

AVLayer autoOrient attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). autoO r i en t Description

The type of automatic orientation to perform for the layer. Type

An AutoO r i en t Ty p e enumerated value; read/write. One of: AutoO r ien t Ty p e.A LO N G _ PAT H AutoO r ien t Ty p e. C A M E R A _ O R _ P O I N T _ O F _ I N T E RE S T AutoO r ien t Ty p e.N O _ AUTO _ O R I E N T

AVLayer blendingMode attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). bl end i ngMo de Description

The blending mode of the layer. Type

A Bl en d i n g Mo de enumerated value; read/write. One of:

43

JavaScript Reference

AVLayer object

44

Bl e n d in g Mod e .AD D Bl e n d in g Mod e .AL PH A _ A DD Bl e n d in g Mod e .C L A S S I C _ C O LOR _ BUR N Bl e n d in g Mod e .C L A S S I C _ C O LOR _ D O D G E Bl e n d in g Mod e .C L A S S I C _ D I F F E R E N C E Bl e n d in g Mod e .C O LOR Bl e n d in g Mod e .C O LOR _ BUR N Bl e n d in g Mod e .C O LOR _ D O D G E Bl e n d in g Mod e .DA N C I N G _ DI S S OLV E Bl e n d in g Mod e .DA R K E N Bl e n d in g Mod e .DA R K E R _ C OLO R Bl e n d in g Mod e .D I F F E R E N C E Bl e n d in g Mod e .D I S SO LVE Bl e n d in g Mod e .E XC LUS I ON Bl e n d in g Mod e .H A R D _ L I G HT Bl e n d in g Mod e .H A R D _ M I X Bl e n d in g Mod e .H UE Bl e n d in g Mod e .L I G H T E N Bl e n d in g Mod e .L I G H T E R _ C O LOR Bl e n d in g Mod e .L I N E A R _ BU R N Bl e n d in g Mod e .L I N E A R _ D O D G E Bl e n d in g Mod e .L I N E A R _ L I G H T Bl e n d in g Mod e .LU M I N E S C E N T _ PR E M U L Bl e n d in g Mod e .LU M I N O S I T Y Bl e n d in g Mod e .M ULT I PLY Bl e n d in g Mod e .N O R M A L Bl e n d in g Mod e .OV E R L AY Bl e n d in g Mod e .PI N _ L I G H T Bl e n d in g Mod e .S AT U RAT I O N Bl e n d in g Mod e .S C R E E N Bl e n d in g Mod e .S I L H OU E T E _ AL PH A Bl e n d in g Mod e .S I L H OU E T T E _ LUM A Bl e n d in g Mod e .S O F T _ L I G HT Bl e n d in g Mod e .S T E N C I L _ A L PHA Bl e n d in g Mod e .S T E N C I L _ LUM A B l e n d in g Mod e . V I V I D _ L I G H T

AVLayer calculateTransformFromPoints() method a pp. pro je c t .i tem ( in d e x) .layer(i n de x ). c al c ul ateTr an s for m From Poi n ts ( p o i n t To p L e f t , p o i n t To p Rig h t , p o i n t B ot to m Ri g ht ) Description

Calculates a transformation from a set of points in this layer. Parameters p o i n tTop Lef t

The top left point coordinates in the form of an array, [ x , y, z ] .

p o i n tTop R i g ht

The top right point coordinates in the form of an array, [x , y, z] .

p o i n tB o ttom R i g h t

The bottom right point coordinates in the form of an array, [x , y, z ] .

44

JavaScript Reference

AVLayer object

45

Returns

An Object with the transformation properties set. Example v ar n ew L ayer = com p.l ayers. ad d (n e wFoo ta ge ); n ew L ayer. th re eD L ayer = t r u e; n e w L aye r. bl e n d i n g Mo de = B l en d i n g Mo d e . AL P H A _ A D D ; v ar t r an s for m = n ew L ayer.c a l c ul ateTr a n s f o r m From Po i n t s ( t l , t r, bl ) ; for(var sel in transform) { n ew L ayer. t r a n sf or m [ se l ]. se tVa lue (t r an sfor m [s el ] ) ; }

AVLayer canSetCollapseTransformation attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). c an S e tCo l l a ps eTr an sfor m at i on Description

True if it is legal to change the value of the co l l a ps eTr an sfor m at i on attribute on this layer. Type

Boolean; read-only.

AVLayer canSetTimeRemapEnabled attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). canSe tTi meRemapE nabled Description

True if it is legal to change the value of the t i m eRem ap E n ab l e d attribute on this layer. Type

Boolean; read-only.

AVLayer collapseTransformation attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). col l apse Tr a n sfor mation Description

True if collapse transformation is on for this layer. Type

Boolean; read/write.

AVLayer effectsActive attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). eff ec ts Ac t ive Description

True if the layer's effects are active, as indicated by the icon next to it in the user interface.

45

JavaScript Reference

AVLayer object

46

Type

Boolean; read/write.

AVLayer frameBlending attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). fr ame Bl end i n g Description

True if frame blending is enabled for the layer. Type

Boolean; read-only.

AVLayer frameBlendingType attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). fr ame Bl end i n gTy p e Description

The type of frame blending to perform when frame blending is enabled for the layer. Type

A Fr a m eBl en di n g Ty p e enumerated value; read/write. One of: Fr am e Bl en d i n g Ty p e. FRAM E _ MI X Fr a m e Bl e n d i n g Ty p e . N O _ F R A M E _ B L E N D Fr a m e Bl e n d i n g Ty p e . PI X E L _ M OT I O N

AVLayer guideLayer attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). guideL ayer Description

True if the layer is a guide layer. Type

Boolean; read/write.

AVLayer hasAudio attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). has Aud i o Description

True if the layer contains an audio component, regardless of whether it is audio-enabled or soloed. Type

Boolean; read-only.

AVLayer hasTrackMatte attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). has Tr a ckMat te

46

JavaScript Reference

AVLayer object

47

Description

True if the layer in front of this layer is being used as a track matte on this layer. When true, this layer's t r a ck Ma tteTy p e value controls how the matte is applied. Type

Boolean; read-only.

AVLayer height attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). heig ht Description

The height of the layer in pixels. Type

Floating-point; read-only.

AVLayer isNameFromSource attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). is Name FromS o urce Description

True if the layer has no expressly set name, but contains a named source. In this case, laye r. n am e has the same value as l ay e r.s ource .nam e . False if the layer has an expressly set name, or if the layer does not have a source. Type

Boolean; read-only.

AVLayer isTrackMatte attribute a pp. pro je c t .i tem ( in d e x) l ayer ( i n d e x) .i s Tr ackMa tte Description

True if this layer is being used as a track matte for the layer behind it. Type

Boolean; read-only.

AVLayer motionBlur attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). mot i onBlur Description

True if motion blur is enabled for the layer. Type

Boolean; read/write.

47

JavaScript Reference

AVLayer object

48

AVLayer preserveTransparency attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). pre s er veTr an s p aren c y Description

True if preserve transparency is enabled for the layer. Type

Boolean; read/write.

AVLayer quality attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). qual i t y Description

The quality with which this layer is displayed. Type

A L ayer Q u a l it y enumerated value; read/write. One of: LayerQu alit y.B EST L ayer Q u al i t y. D RA F T L ayer Q u al i t y. W I R E F RA M E

AVLayer replaceSource() method a pp. pro je c t .i tem ( in d e x) .layer(i n de x ). rep l a ce S ource ( n e w S ource , f i xE x pre ss i on s ) Description

Replaces the source for this layer. Parameters n e w S o u rce

The new source AVItem object.

f i xE x pres si o n s

Tr ue to adjust expressions for the new source, fa l se otherwise. Note that this feature can be resource-intensive; if replacing a large amount of footage, do this only at the end of the operation. See also “Project autoFixExpressions() method” on page 111.

Returns

Nothing.

AVLayer source attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). so urce Description

The source AVItem for this layer. The value is null in a Text layer. Use AV L ayer.rep l a c e S o u rce ( ) to change the value. Type

AVItem object; read-only.

48

JavaScript Reference

AVLayer object

49

AVLayer sourceRectAtTime() method a pp. pro je c t .i tem ( in d e x) .layer(i n de x ). so urceRe c tAt Ti me (t im e T, e x te n t s ) Description

Retrieves the rectangle bounds of the layer at the specified time index, corrected for text or shape layer content. Use, for example, to write text that is properly aligned to the baseline. Parameters t i m eT

The time index, in seconds. A floating-point value.

extents

Tr ue to include the extents, fa l se otherwise. Extents apply to shape layers, increasing the size of the layer bounds as necessary.

Returns

A JavaScript object with four attributes, [ top, lef t , w id t h, h eig h t] .

AVLayer threeDLayer attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). th re eD Layer Description

True if this is a 3D layer. Type

Boolean; read/write.

AVLayer threeDPerChar attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). th re eD PerChar Description

True if this layer has the Enable Per-character 3D switch set, allowing its characters to be animated off the plane of the text layer. Applies only to text layers. Type

Boolean; read/write.

AVLayer timeRemapEnabled attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). t im eRemap E na b le d Description

True if time remapping is enabled for this layer. Type

Boolean; read/write.

49

JavaScript Reference

AVLayer object

50

AVLayer trackMatteType attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). t r a ck Ma tte Ty p e Description

If this layer has a track matte, specifies the way the track matte is applied. Type

A Tr a ck Ma tte Ty p e enumerated value; read/write. One of: Tr a ck Mat teTy p e. AL PH A Tr a ck Mat teTy p e. AL PH A_ I N VE RT E D Tr a ck Mat teTy p e. LUM A Tr a ck Ma t teTy p e . LU M A _ I N V E RT E D Tr a ck Mat teTy p e. N O_ T RAC K _ MAT T E

AVLayer width attribute a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ). w i d th Description

The width of the layer in pixels. Type

Floating-point; read-only.

50

JavaScript Reference

CameraLayer object

51

CameraLayer object a pp. pro je c t .i tem ( in d e x) .l ayer(i n de x ) Description

The CameraLayer object represents a camera layer within a composition. Create it using the LayerCollection object’s a d dC am er a method; see “LayerCollection addCamera() method” on page 94. It can be accessed in an item’s layer collection either by index number or by a name string. • CameraLayer is a subclass of Layer. All methods and attributes of Layer are available when working with

CameraLayer. See “Layer object” on page 84. AE Properties

CameraLayer defines no additional attributes, but has different AE properties than other layer types. It has the following properties and property groups: Ma r ker Tr an s for m Poi n t of In teres t Pos i t i on S c al e Orientation X Rot at i on Y Rot at i o n Rot at i o n O p a ci t y C a m e r a O p t i on s Zoom D ep th of F i e ld Foc u s D i st an ce Blu r Le ve l

51

JavaScript Reference

Collection object

52

Collection object Like an array, a collection associates a set of objects or values as a logical group and provides access to them by index. However, most collection objects are read-only. You do not assign objects to them yourself—their contents update automatically as objects are created or deleted. The index numbering of a collection starts with 1, not 0. Objects Object

Reference

Description

ItemCol l ec t i on

“ItemCollection object” on page 80 All of the items (imported files, folders, solids, and so on) found in the Project panel.

L ayer Co l l e c t i on

“LayerCollection object” on page 93

O MCol l ec t i on

“OMCollection object” on page 105 All of the Output Module items in the project.

RQ Item Col le c t ion

“RenderQueueItem object” on page 156

All of the layers in a composition.

All of the render-queue items in the project.

Attributes length

The number of objects in the collection.

Methods []

Retrieves an object in the collection by its index number. The first object is at index 1.

52

JavaScript Reference

CompItem object

53

CompItem object a pp. pro je c t .i tem ( i n d e x) a pp. pro je c t .i tem s [ inde x ] Description

The CompItem object represents a composition, and allows you to manipulate and get information about it. Access the objects by position index number in a project’s i te m collection. • CompItem is a subclass of AVItem, which is a subclass of Item. All methods and attributes of AVItem and

Item, in addition to those listed below, are available when working with CompItem. See “AVItem object” on page 32 and “Item object” on page 77. Example

Given that the first item in the project is a CompItem, the following code displays two alerts. The first shows the number of layers in the CompItem, and the second shows the name of the last layer in the CompItem. v ar f i r s t Co m p = a p p. p ro je c t .i te m ( 1 ) ; a l er t ( " nu m b e r o f l ayer s i s " + f i r s t Co m p.num L aye r s ) ; a l er t( " n a m e of l a st l ayer i s " + f i rs t Co m p.l ayer ( f i r s t Com p.n u m L aye rs ) . n a m e ) ; Attributes Attribute

Reference

f r a m eD ur a t i on

“CompItem frameDuration attribute” on The duration of a single frame. page 56

wor k Area St ar t

“CompItem workAreaStart attribute” on The work area start time. page 60

wor k Area D ur a ti on

“CompItem workAreaDuration attribute” on page 59

The work area duration.

nu m L ayers

“CompItem numLayers attribute” on page 57

The number of layers in the composition.

h id eS hy L ayers

“CompItem hideShyLayers attribute” on When true, shy layers are visible in the Timeline panel. page 56

mo tionBlu r

“CompItem motionBlur attribute” on page 57

When true, motion blur is enabled for this composition.

d r a ft 3 d

“CompItem draft3d attribute” on page 55

When true, Draft 3D mode is enabled for the Composition panel.

f r a m e Bl e n di n g

“CompItem frameBlending attribute” on When true, time filtering is enabled for this composipage 55 tion.

preser veNeste d Fr a m eRa te

“CompItem preserveNestedFrameRate attribute” on page 57

When true, the frame rate of nested compositions is preserved.

preser veNeste d Resolut i on “CompItem preserveNestedResolution

When true, the resolution of nested compositions is preserved.

attribute” on page 58

Description

b g Co lor

“CompItem bgColor attribute” on page 54

The background color of the composition.

a c t iveC am er a

“CompItem activeCamera attribute” on page 54

The current active camera layer.

d i sp l ay S ta r t Ti m e

“CompItem displayStartTime attribute” on page 55

Changes the display of the start time in the Timeline panel.

53

JavaScript Reference

CompItem object

54

Attribute

Reference

Description

res o lut i o n Fa c to r

“CompItem resolutionFactor attribute” on page 58

The factor by which the x and y resolution of the Composition panel is downsampled.

s hu t ter A n g l e

“CompItem shutterAngle attribute” on page 59

The camera shutter angle.

s hu t ter P h a se

“CompItem shutterPhase attribute” on page 59

The camera shutter phase.

l ayer s

“CompItem layers attribute” on page 57 The layers of the composition. “LayerCollection object” on page 93

s e l e c te d L ayer s

“CompItem selectedLayers attribute” on The selected layers of the composition. page 59

s e l e c t e d Pro p e r t i e s

“CompItem selectedProperties attribute” on page 59

The selected properties of the composition.

renderer

“CompItem renderer attribute” on page 58

The rendering plug-in module to be used to render this composition.

renderers

“CompItem renderers attribute” on page 58

The set of available rendering plug-in modules.

Methods Method

Reference

Description

du pl i c ate( )

“CompItem duplicate() method” on page 55

Creates and returns a duplicate of this composition.

l ayer ()

“CompItem layer() method” on page 56

Gets a layer from this composition.

CompItem activeCamera attribute a pp. pro je c t .i tem ( in d e x) .a c t iveC am er a Description

The active camera, which is the front-most camera layer that is enabled. The value is null if the composition contains no enabled camera layers. Type

CameraLayer object; read-only.

CompItem bgColor attribute a pp. pro je c t .i tem ( in d e x) .b g Co l or Description

The background color of the composition. The three array values specify the red, green, and blue components of the color. Type

An array containing three floating-point values, [R, G, B], in the range [0.0..1.0]; read/write.

54

JavaScript Reference

CompItem object

55

CompItem displayStartTime attribute a pp. pro je c t .i tem ( in d e x) .d i sp l ay S ta r t Ti m e Description

The time set as the beginning of the composition, in seconds. This is the equivalent of the Start Timecode or Start Frame setting in the Composition Settings dialog box. Type

Floating-point value in the range [0.0...86339.0] (1 second less than 25 hours); read/write.

CompItem draft3d attribute a pp. pro je c t .i tem ( in d e x) .d r a ft 3 d Description

When true, Draft 3D mode is enabled for the Composition panel. This corresponds to the value of the Draft 3D button in the Composition panel. Type

Boolean; read/write.

CompItem duplicate() method a pp. pro je c t .i tem ( in d e x) .d u p li c a te ( ) Description

Creates and returns a duplicate of this composition, which contains the same layers as the original. Parameters

None. Returns

CompItem object.

CompItem frameBlending attribute a pp. pro je c t .i tem ( in d e x) .f r a m e Bl e n d in g Description

When true, frame blending is enabled for this Composition. Corresponds to the value of the Frame Blending button in the Composition panel. Type

Boolean; if true, frame blending is enabled; read/write.

55

JavaScript Reference

CompItem object

56

CompItem frameDuration attribute a pp. pro je c t .i tem ( in d e x) .f r a meD ur at i on Description

The duration of a frame, in seconds. This is the inverse of the f r am e R a te value (frames-per-second). Type

Floating-point; read/write.

CompItem hideShyLayers attribute a pp. pro je c t .i tem ( in d e x) .h id eS hy L ayers Description

When true, only layers with s hy set to false are shown in the Timeline panel. When false, all layers are visible, including those whose shy value is true. Corresponds to the value of the Hide All Shy Layers button in the Composition panel. Type

Boolean; read/write.

CompItem layer() method a pp. pro je c t .i tem ( in d e x) .l ayer (i n de x ) a pp. pro je c t .i tem ( in d e x) .l ayer (o t he rLaye r, re l In de x ) a pp. pro je c t .i tem ( in d e x) .l ayer (n a m e) Description

Returns a Layer object, which can be specified by name, an index position in this layer, or an index position relative to another layer. Parameters i n dex

The index number of the desired layer in this composition. An integer in the range [1...numLayers], where n u m Laye r s is the number of layers in the composition.

—or— otherL ayer

A Layer object in this composition. The re lIn d ex value is added to the index value of this layer to find the position of the desired layer.

rel In dex

The position of the desired layer, relative to o ther L ayer . An integer in the range [1–oth erL ayer. in d ex . . . numLayers–o ther L ayer.index ], where n u m Laye r s is the number of layers in the composition. This value is added to the otherL ayer value to derive the absolute index of the layer to return.

—or— name

The string containing the name of the desired layer.

56

JavaScript Reference

CompItem object

57

Returns

Layer object.

CompItem layers attribute a pp. pro je c t .i tem ( in d e x) .l ayers Description

A LayerCollection object that contains all the Layer objects for layers in this composition. See “LayerCollection object” on page 93. Type

LayerCollection object; read-only.

CompItem motionBlur attribute a pp. pro je c t .i tem ( in d e x) .m o t io n B lu r Description

When true, motion blur is enabled for the composition. Corresponds to the value of the Motion Blur button in the Composition panel. Type

Boolean; read/write.

CompItem numLayers attribute a pp. pro je c t .i tem ( in d e x) .nu m L ayers Description

The number of layers in the composition. Type

Integer; read-only.

CompItem preserveNestedFrameRate attribute a pp. pro je c t .i tem ( in d e x) .preser veNe ste d Fr a m eR ate Description

When true, the frame rate of nested compositions is preserved in the current composition. Corresponds to the value of the “Preserve frame rate when nested or in render queue” option in the Advanced tab of the Composition Settings dialog box. Type

Boolean; read/write.

57

JavaScript Reference

CompItem object

58

CompItem preserveNestedResolution attribute a pp. pro je c t .i tem ( in d e x) .preser veNe ste d Resolut i on Description

When true, the resolution of nested compositions is preserved in the current composition. Corresponds to the value of the “Preserve Resolution When Nested” option in the Advanced tab of the Composition Settings dialog box. Type

Boolean; read/write.

CompItem renderer attribute a pp. pro je c t .i tem ( in d e x) .renderer Description

The current rendering plug-in module to be used to render this composition, as set in the Advanced tab of the Composition Settings dialog box. Allowed values are the members of c o m p Ite m .renderers . Type

String; read/write.

CompItem renderers attribute a pp. pro je c t .i tem ( in d e x) .renderers Description

The available rendering plug-in modules. Member strings reflect installed modules, as seen in the Advanced tab of the Composition Settings dialog box. Type

Array of strings; read-only.

CompItem resolutionFactor attribute a pp. pro je c t .i tem ( in d e x) .res o lut i o n Fa c to r Description

The x and y downsample resolution factors for rendering the composition. The two values in the array specify how many pixels to skip when sampling; the first number controls horizontal sampling, the second controls vertical sampling. Full resolution is [1,1], half resolution is [2,2], and quarter resolution is [4,4]. The default is [1,1]. Type

Array of two integers in the range [1..99]; read/write.

58

JavaScript Reference

CompItem object

59

CompItem selectedLayers attribute a pp. pro je c t .i tem ( in d e x) .s e l e c te d L ayer s Description

All of the selected layers in this composition. This is a 0-based array (the first object is at index 0). Type

Array of Layer objects; read-only.

CompItem selectedProperties attribute a pp. pro je c t .i tem ( in d e x) .s e l e c t e d Pro p e r t i e s Description

All of the selected properties (Property and PropertyGroup objects) in this composition. The first property is at index position 0. Type

Array of Property and PropertyGroup objects; read-only.

CompItem shutterAngle attribute a pp. pro je c t .i tem ( in d e x) .s hu t ter A n g l e Description

The shutter angle setting for the composition. This corresponds to the Shutter Angle setting in the Advanced tab of the Composition Settings dialog box. Type

Integer in the range [0...720]; read/write.

CompItem shutterPhase attribute a pp. pro je c t .i tem ( in d e x) .s hu t ter P h a se Description

The shutter phase setting for the composition. This corresponds to the Shutter Phase setting in the Advanced tab of the Composition Settings dialog box. Type

Integer in the range [–360...360]; read/write.

CompItem workAreaDuration attribute a pp. pro je c t .i tem ( in d e x) .wor k Area D ur a t ion Description

The duration of the work area in seconds. This is the difference of the start-point and end-point times of the Composition work area.

59

JavaScript Reference

CompItem object

60

Type

Floating-point; read/write.

CompItem workAreaStart attribute a pp. pro je c t .i tem ( in d e x) .wor k Area St ar t Description

The time when the Composition work area begins, in seconds. Type

Floating-point; read/write.

60

JavaScript Reference

FileSource object

61

FileSource object a pp. pro je c t .i tem ( in d e x) . m a i n S o u rce a pp. pro je c t .i tem ( in d e x) .p roxySo urce Description

The FileSource object describes footage that comes from a file. • FileSource is a subclass of FootageSource. All methods and attributes of FootageSource, in addition to those

listed below, are available when working with FileSource. See “FootageSource object” on page 68. Attributes Attribute

Reference

Description

f i le

“FileSource file attribute” on page 61

The file that defines this asset.

m i s s i n g Fo ot a g e Pat h

“FileSource missingFootagePath attribute” The file that contains footage missing from this asset. on page 61

Methods Method

Reference

Description

rel o a d ()

“FileSource reload() method” on page 62

Reloads the asset from the file, if it is a m a in S o u rce of a FootageItem.

FileSource file attribute a pp. pro je c t .i tem ( i n d e x) .m a i n S o u rce .f il e a pp. pro je c t .i tem ( i n d e x) .p roxy S o u rce . fi l e Description

The ExtendScript File object for the file that defines this asset. To change the value: • If this FileSource is a prox y S ource of an AVItem, call s e t Prox y ( ) or se tProx y Wi th S equ ence( ) . • If this FileSource is a m a i n S o u rce of a FootageItem, call rep l ace( ) or repla ceWith S equence() . Type

File object; read-only.

FileSource missingFootagePath attribute a pp. pro je c t .i tem ( i n d e x) . m a i n S o u rce . f il e .m i s s i n g Fo o t a g e Pat h a pp. pro je c t .i tem ( i n d e x) .p roxy S o u rce . fi l e .m is s in g Fo o t ag e Pa th Description

The path and filename of footage that is missing from this asset. See also “AVItem footageMissing attribute” on page 33. Type

String; read-only.

61

JavaScript Reference

FileSource object

62

FileSource reload() method a pp. pro je c t .i tem ( i n d e x) . m a i n S o u rce . f il e .m a i n S o u rce. re l o ad ( ) Description

Reloads the asset from the file. This method can be called only on a m a i n S o u rce , not a p roxy S o u rce . Parameters

None. Returns

Nothing.

62

JavaScript Reference

FolderItem object

63

FolderItem object a pp. pro je c t .FolderItem Description

The FolderItem object corresponds to a folder in your Project panel. It can contain various types of items (footage, compositions, solids) as well as other folders. Example

Given that the second item in the project is a FolderItem, the following code puts up an alert for each top-level item in the folder, showing that item’s name. v ar secondItem = app.proj ec t. item(2 ); if ( !(secondItem inst anceof Fo lderItem) ) { a l er t("problem: se cond item is no t a folder"); } else { for ( i = 1 ; i Import > File dialog box. Type

Boolean; read/write.

ImportOptions importAs attribute imp or t O p t i ons .imp or tAs Description

The type of object for which the imported file is to be the source. Before setting, use can Im p or tAs to check that a given file can be imported as the source of the given object type. See “ImportOptions canImportAs() method” on page 74. Type

An Im p o r t AsTy p e enumerated value; read/write. One of: Im p o r tAs Ty p e .C O M P _ C RO PPE D _ L AYE R S Im p o r tAs Ty p e .F O OTAG E Im p o r tAs Ty p e .C O M P Im p o r tAs Ty p e .P ROJ E C T

75

JavaScript Reference

ImportOptions object

76

ImportOptions sequence attribute imp or t O p t i ons .s e quence Description

When true, a sequence is imported; otherwise, an individual file is imported. Type

Boolean; read/write.

76

JavaScript Reference

Item object

77

Item object a pp. pro je c t .i tem ( i n dex ) a pp. pro je c t .i te m s [ in d ex ] Description

The Item object represents an item that can appear in the Project panel. The first item is at index 1. • Item is the base class for AVItem and for FolderItem, which are in turn the base classes for various other

item types, so Item attributes and methods are available when working with all of these item types. See “AVItem object” on page 32 and “FolderItem object” on page 63. Attributes Attributes

Reference

Description

name

“Item name attribute” on page 78

The name of the object as shown in the Project panel.

com m e n t

“Item comment attribute” on page 78

A descriptive string.

id

“Item id attribute” on page 78

A unique identifier for this item.

p aren tFol de r

“Item parentFolder attribute” on page 78

The parent folder of this item.

s e l e c te d

“Item selected attribute” on page 79

When true, this item is currently selected.

t y p e Na m e

“Item typeName attribute” on page 79

The type of item.

Method

Reference

Description

rem ove( )

“Item remove() method” on page 79

Deletes the item from the project.

Methods

Example

This example gets the second item from the project and checks that it is a folder. It then removes from the folder any top-level item that is not currently selected. It also checks to make sure that, for each item in the folder, the parent is properly set to the correct folder. v ar my Folder = a pp.proje c t.item (2); i f (my Fo ld e r. t y p e Nam e ! = " Fo l d e r " ) { a l er t( " e r ro r : s e con d i te m i s n o t a fo ld e r " ); } e l se { v ar nu mInFolder = my Fo lder.numItems; / / A lw ay s r u n l o o p s b a ck wa rds w h en del e t i n g th i n g s: f o r ( i = n u m In Fo l d e r ; i > = 1 ; i- - ) { v ar c ur Item = my Fol d er. item (i ) ; i f ( c ur Item .p aren tFol der != myFol der ) { a l er t( "er ror w i th in A E : t he p arent Fold er i s no t s et cor re c t ly") ; } e l se { i f ( ! c u rIte m . s e l e c t e d & & c u r Item . t y p eNam e = = " Fo ot a g e " ) { / / fo un d a n u n se l e c te d s o l i d . c u r Item . rem ove ( ) ;

77

JavaScript Reference

Item object

78

} } } }

Item comment attribute a pp. pro je c t .i tem ( in d e x) .com m en t Description

A string that holds a comment, up to 15,999 bytes in length after any encoding conversion. The comment is for the user's purpose only; it has no effect on the item's appearance or behavior. Type

String; read/write.

Item id attribute a pp. pro je c t .i tem ( in d e x) .i d Description

A unique and persistent identification number used internally to identify an item between sessions. The value of the ID remains the same when the project is saved to a file and later reloaded. However, when you import this project into another project, new IDs are assigned to all items in the imported project. The ID is not displayed anywhere in the user interface. Type

Integer; read-only.

Item name attribute a pp. pro je c t .i te m ( i n dex ) .n a m e Description

The name of the item as displayed in the Project panel. Type

String; read/write.

Item parentFolder attribute a pp. pro je c t .i tem ( in d e x) .p aren t Fol d er Description

The FolderItem object for the folder that contains this item. If this item is at the top level of the project, this is the project's root folder (a p p.p ro je c t .ro o t Fol d e r ). You can use the ItemCollection’s ad d Fo l d e r method to add a new folder, and set this value to put items in the new folder. See “ItemCollection addFolder() method” on page 80.

78

JavaScript Reference

Item object

79

Type

FolderItem object; read/write. Example

This script creates a new FolderItem in the Project panel and moves compositions into it. / / c re a t e a n e w Fol d e r Ite m i n p ro j e c t , w i t h n a m e “co m p s” v ar compFolder = app.proj ec t. items. a ddFo l der(“com ps” ); / / m ove a l l com p o s i t i o n s i n t o n e w f o l d e r by s e t t in g / / com p Ite m’s p a ren t Fol d e r to “com p s” f o l d e r for ( v a r i = 1 ; i