Per-Character Scripting Public Beta Announcement

[Sébastien Périer]

Hi everyone, 

With After Effects (Beta) 24.2.0 build 17, we have added some very significant and long-awaited additions to the TextDocument DOM:

• The properties of individual characters can now be changed independently of the others with the new CharacterRange and ParagraphRange objects. 
• New paragraphCount attribute will return the number of paragraphs in the TextDocument. 
• New paragraphCharacterIndexesAt method will return the paragraph bounds from a character index—useful if you have a character index and wonder what the character index bounds of the paragraph it is part of. 
• It is now possible to faithfully round trip a mixed-property Text Layer via the TextDocument without losing individual properties. 
• boxTextPos will now accept negative values (this was a long-standing bug.) 

You can read the updated docs here: https://ae-scripting.docsforadobe.dev/introduction/changelog.html. 

The CharacterRange and ParagraphRange will benefit from a short explanation. 

The former is returned by the characterRange() function where the parameters are character indexes, and the latter by the paragraphRange() function where the parameters are paragraph indexes. With them, you have all the same familiar character and paragraph properties that are available on the TextDocument, but now they apply to the effective character index range which was used to construct the specific range object. 

For example: 

var td = ....layer(1).property(“Source Text”).value; 
td.text; => “Hello, World!” 
var cr = td.characterRange(0,5); 
cr.text; => “Hello” 
cr.text = “After Effects”; // replace “Hello” with “After Effects” 
cr.text; => “After” 
td.text; => “After Effects, World!” 

Though these new objects share the same character and paragraph property definitions, there are still a few differences of note. 

• A TextDocument character attribute on read returns the attribute's value for the first character in the Text layer, but on write applies it to the whole Text layer. Because of this, a TextDocument character property is never mixed. 
• A TextDocument paragraph attribute on read and write is for all the characters in the Text layer. Because of this, a TextDocument paragraph property can be mixed. 
• A CharacterRange and ParagraphRange object can return mixed if the range exceeds one character or paragraph, mixed is always indicated by returning undefined (except for .justification). 
• The TextDocument fillColor and strokeColor will throw an exception on read if the corresponding applyFill and applyStroke properties are not set - the CharacterRange and ParagraphRange objects will not. 

We have built a demo script exercising the new CharacterRange and ParagraphRange hooks to get you started. You can get it from our Github repository: https://github.com/AdobeDocs/after-effects/blob/main/samples/PerCharacter_StyleEdit_ScriptUISample.j...
 
Remember, these scripting hooks are currently in Beta and are subject to change. 
 
We can't wait to see what you'll be building with these new hooks. 

 

 Douglas, John and Sebastien 

[A. Cobb]

Here's an AE project file demonstrating a method for measuring the dimensions of individual words using text animators and expressions. This can also work for individual characters or lines, by changing the relevant text animators to index based on those units. It works by using negative comp time values (i.e. the time before frame 0) as a sort of scratchpad for isolating and measuring the individual words. Each word is isolated at the negative value of its respective index in seconds, i.e. the first word is at t = -1, the second word at t = -2, and by calling sourceRectAtTime(t) you can get the sourceRect for just that word.

This only works for text that isn't animated internally, meaning you can transform the text all you like, but once you apply text animators all bets are off, since this method depends on each word being at the same location in local layer space at different times. 

[JohnColombo · Accepted solution]

Hi all,

Thank you so much for your feedback on these new per-character scripting APIs. We are happy to announce that these are available for use in the release version of After Effects 24.3. The documentation on https://ae-scripting.docsforadobe.dev/ has also been updated to reflect the wider release of the APIs.

Thanks again,

- Douglas, John,and Sebastien