Community Manager

Answered

Per-Character Scripting Public Beta Announcement

Forum|Forum|2 years ago
November 20, 2023
8 replies
16603 views

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.jsx

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

This topic has been closed for replies.

Correct answer JohnColombo17100380

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

JohnColombo17100380

Correct answer

Community Manager

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

P

Paul Tuersley

Inspiring

@Douglas_Waterfall Do you have any thoughts on how best to identify mixed styles in an existing text layer? An obvious example would be doing find/replace on a certain font or color inside a mix style text layer.

It looks like I can characterRange the whole text then say, see if font comes back undefined, then continue to drill down ever more fine grained (or characterRange each pair of characters, or just compare every single character). But of course there are any number of font attributes that can be different between each character.

Ideally it would be something like returning and array of character ranges that encompassed every difference, or we could choose between all attributes or just certain ones. I realise that is something we can potentially code, even if it's fiddly and laborious.

It appears that any time you set a character range, it will push the style settings for the first character onto all characters in that range. Not entirely surprising although I hoped it would just touch the altered attributes. That suggests the safest alternative would be to set each character one at a time, but that seems non-ideal.

D

Douglas_Waterfall

Adobe Employee

Hi Paul.

After Effects does not have styles (or exposes them) so there is no exposed concept of "difference".

Thus attributes just are without a claim to one value being more important than another.

If you are looking for mixed attributes then the only way to do it is indeed to walk each character and find out what the attribute is and see if it does not match what you expected.

The only style we have is conceptually default which is what you get when you call resetChar/ParaStyle in the UI or in scripting. Having an API which would return overrides relative to this style has seemed useful to me, and it is on my list to explore. However, I do not think this would help you with figuring out different overrides on a span of text.

Not sure what you mean by this:

It appears that any time you set a character range, it will push the style settings for the first character onto all characters

Unless you've discovered a bug, setting an attribute via a CharacterRange immediately applies only that attribute to the range of character spanned by the CharacterRange. Likewise if you read the attribute, we access that same range and return the value or mixed, as appropriate.

Sounds like you are seeing something different, or have a different mental model of what is going on. If you the former - I want to know about it immediately.

Perhaps you mean what happens when you apply text via a CharacterRange? That is implemented internally as a delete/insert operation so after the delete only one set of attributes remains and those then are extended as the text is inserted. Think about what happens when you interact with a TextLayer by hand - it is the same conceptual model.

Are you perhaps trying to replace text character for character and preserve the original styling?

Douglas Waterfall

After Effects Engineering

P

Paul Tuersley

Inspiring

When I talk about styles I basically just mean all the various different text attributes. I realise there aren't any style groups as such. Yes I'm talking about making only certain changes while preserving all other styling.

And yes I meant apply text via the CharacterRange. I had two characters with different colors, used CharacterRange to change the text for those two characters and the second character got the first character's color. It makes sense when you describe it as an insert/delete.

Manual editing text does let you select a character range and then only affect the attribute being changed in the Character Panel, so I hoped perhaps it would be more like that. So I was just checking if there might be some fast track to know if or where those differences existed. But that's fine. I was already beginning to suspect character by character was the only way and it is at least possible now.

I guess I could grab a CharacterRange for the whole text and check every single exposed text attribute (I'm not sure if everything has been exposed yet, but it's probably close enough), then if any come back as undefined I will know to create a CharacterRange for each character one at a time to apply whatever specific attribute changes are required. Maybe because I'm just editing the CharacterRange / TextDocument rather than repeatedly applying it to the SourceText prop it won't be too slow.

Just doing a search/replace on say font or color that preserves all other styles is a lot easier for me to wrap my head around than what to do when changing the text characters in an existing mixed style text layer. I guess at that point the user really needs to be selecting ranges and editing manually in the comp so the intent is clear.

I could preserve the styles but any change in character length would not result in those styles shuffling accordingly. Unless I did come up with a solution for splitting then into groups of matching attributes then present them for editing in that way.

Thanks as always.

Paul

D

Douglas_Waterfall

Adobe Employee

And we are back with a heads up on the API update and more detail.

Starting with beta build 24.3.0/25 we have made the following breaking changes.

We have removed all the text properties from the ParagraphRange object (ie. font, fontSize, etc).
We have added a new function, ParagraphRange.characterRange() which will return a CharacterRange object initialized to the (characterStart, characterEnd) from the ParagraphRange.

What this means in effect is that instead of doing this:

var td = ...value();
var pr = td.paragraphRange(0);
pr.fontSize = 4;
pr.fillColor = [1,0,0];

You should do this:

var td = ...value();
var pr = td.paragraphRange(0);
// fastest
var cr = pr.characterRange();
cr.fontSize = 4;
cr.fillColor = [1,0,0];
// slower
pr.characterRange().fontSize = 4;
pr.characterRange().fillColor = [1,0,0];

Also part of this build will be a new scripting object, ComposedLineRange... but I wll leave you to read the docs for that.

Douglas Waterfall

After Effects Engineering

Mathias Moehl

Community Expert

Wow, ComposedLineRange is amazing!
Should finally give me a reliable way to figure out the lines of a box text 🙂

Mathias Möhl - Developer of tools like BeatEdit and Automation Blocks for Premiere Pro and After Effects

D

Douglas_Waterfall

Adobe Employee

Just a quick update on the status of this, as it has been in Beta for a while and I expect a number of gentle readers are patiently waiting for this to appear in a full release.

We have elected to hold this back from the upcoming 24.2 release as we wish to make a substantial change to the API for the ParagraphRange object first.

What we are planning to do is remove all the text properties from the ParagraphRange and substitute them for a single API which will return a CharacterRange object which is initialized to the start/end character index values of the ParagraphRange.

var pr = textDocument.paragraphRange(5);
var cr = pr.characterRange(); // note, no parameters
cr.fontSize = 72;
cr.font = "Helvetica";

Our motivation for this is performance related - each time any text property of a ParagraphRange instance is accessed the start/end character index has to be computed based on the nTh paragraph reference - for single or small paragraph Text Layers this is not that important, but a Text Layer consisting of a long film credit with each contributor getting their own paragraph...not so good.

We will let you know shortly before this change shows up in a Beta release.

Douglas Waterfall

After Effects Engineering

A

Alex27210127xrfb

New Participant

Is it possible for one to stay on a older beta build without updating so we can wait for the next implementation of the character scripting?

dbDavideBoscolo

Brainiac

Is there any way to know whether a character is/isn't selected?
If not, can it be added please?

dbDavideBoscolo

Brainiac

What about this guys?

T

Thomas Ladorian

New Participant

Will this be avalaible for expressions too or just for scripting?

Having it in expressions would make my life so much easier to create and update some templates I use almost everyday.

D

Douglas_Waterfall

Adobe Employee

Hi @Thomas Ladorian

This update is only "just" for scripting.

I have some questions I would like to ask you about your Expressions workflow, if you can spare the time - send me a letter via forum mail.

Douglas Waterfall

After Effects Engineering

A

Aaron Cobb

Inspiring

Expressions access to these features would be a pretty big deal for me as well. I'm frequently have to find workarounds to accommodate designs with mixed typefaces, and I hate having to impose limitations on the designers who create these looks or on the editors who will have to navigate complicated controls and weird constraints when using the templates I build.