Scripting: New and updated APIs for Font Management

[Sébastien Périer]

Hi everyone,

Starting with AE 24.4.0.24 beta, we have introduced a number of miscellaneous Font management APIs which we hope will be super interesting to some of you who have more refined workflows around Fonts - we created them to help our internal testing, and decided to expose them to Beta following your feedback.

As always, we have updated the Scripting Documentation, where you will find more detailed information about these new APIs. Here is a quick overview of the new APIs:

app.fonts.fontsDuplicateByPostScriptName
Having more than one Font instance which has the same PostScript name can lead to surprises when the Font instance you thought you were going to get was not the one the FontServer handed back. Earlier releases of After Effects were prone to crash in this state and one of the focuses of the last year of FontServer work was to make this situation work.

Simply use the TextDocument.font API to select a Font by PostScript name is problematic when there is more than one Font instance with the same PostScript name - did the FontServer select the one you wanted?

app.fonts.mruFontFamilyList
app.fonts.favoriteFontFamilyList
Access to Most Recently Used (MRU), and Favorites font lists anywhere you can choose fonts from these lists. Ever wanted to clear these lists? Just pass in an empty array.
Want to define your own Favorites programmatically rather than clicking in the UI? Here is the way.

app.fonts.freezeSyncSubstitutedFonts
By default when After Effects opens a Project, and it finds that it has a Font reference which does not exactly match an installed Font, it will attempt to activate an Adobe Font with the same PostScript name if it can find one there. Not all workflows want this to happen - a popular reason being server workflows where they never want to use Adobe Fonts and so the automatic install just makes the Font environment more complicated for them. This API will disable the automatic activation from Adobe Fonts.

app.fonts.substitutedFontReplacementMatchPolicy
When After Effects has a missing Font reference when opening a Project, which appears in the UI as a bracket font name at the bottom of the Character Panels, it will automatically look in the Font environment to find a candidate Font to replace it with.

Consider the case where a Project file was saved using Courier on Windows, and then opened on the Mac. If the two installed Font instances do not share the same Font properties that After Effects requires, it will be treated as a missing Font reference when opened on the Mac.
It is longstanding behavior in After Effects to silently allow this sort of quiet substitution, and so by default when evaluating a missing Font reference we only require that we find another Font instance that has the same PostScript name to replace it.

All this happens automatically but do be aware that the Project IS changed by the replacement of the original referenced Font with the replacement Font. If this Project was saved and brought back to Windows the same thing would happen again in reverse.

Some workflows do not want this loose behavior at all - a close substitute, merely by PostScript name, is not acceptable to them. It is better to realize the Font is missing and go find it than have the composition change in a silent and potentially undesired way.

Other workflows do not want any replacement at all - a popular assumption being that all the Fonts should have been already installed so why is anything missing at all?
This API provides these two additional policies over the default PostScript-name-only one.

app.fonts.pollForAndPushNonSystemFontFoldersChanges
Finally, erver-based workflows which need to add and remove their own Font instances through scripting without resorting to using the OS tools, have a challenge in getting After Effects to notice that the Font environment has changed through their actions.

Fonts that are changed through the OS tools, and by Adobe Fonts activation, are automatically detected but Fonts that are changed in the Application Support Fonts folder (and the equivalent on Windows) are not detected until After Effects restarts or the Font environment changes in folders which are automatically detected. This experimental API allows the scripter to give the Font environment a little push to recognize if the Font environment has changed outside of the System Font folders, and it has it will schedule an update to the Font environment to process it.

It has been requested that we expose the ability to dynamically add additional Font search folders - it is something we are considering.

As always we are interested in hearing about the successful use of these APIs and feedback on how they might be made better for your workflow.

Douglas Waterfall, John Colombo & Sébastien Périer
After Effects Engineering

[Paul Tuersley]

I've been using app.fonts.mruFontFamilyList and app.fonts.favoriteFontFamilyList and they're working great! I'd only really considered syncing favorites but now I've played with mru it's equally useful.

A slight issue is the Character/Properties panels needs a bump (like collapsing/uncollapsing the panel or selecting a text layer) before the font list updates after receiving new string arrays, which will give users an initial impression that it hasn't changed.

[Douglas_Waterfall]

Hi @Paul Tuersley , glad you found this.

The CharPanel updates itself on the idle task so a change to the font environment does not instantly trigger an update there.

I am away from my work computer for a while so I cannot remind myself what the code does when these lists change.

You might try to $.sleep(1000) to see if I thought ahead on this.

Changing the sort order, Show English Names, does handle this properly but I do not remember if that was exposed to scripting.

Adding or removing a font will trigger recognition as well - even if only a custom variable one.

Douglas Waterfall

After Effects Engineering 

[Paul Tuersley]

$.sleep(1000) doesn't seem to do it, and I don't think sort order or Show English Names are exposed.

Is this likely something that can be addressed without needing some workaround? I'm not in any hurry for a solution.

[Douglas_Waterfall]

It should be automatic without any workarounds but I missed it - you were my target customer.

I will fix this when I return to the office.

You might try Favorites after syncing Source Code Pro from Adobe Fonts - these are partial duplicates with what is in the App package. I had to do something weird and obscure to get the old UI code to show them both - append space(s) to the duplicate family instances when it is registered with the UI.

Not sure there is a better solution, though I suppose I could expose an API on the Font to return the FavoritesFamilyName.  Yuck.

Douglas Waterfall

After Effects Engineering

[Paul Tuersley]

Just using family names did strike me as curious against the backdrop of previous talk we've had on edge cases, but I've not sourced a suitable selection of problem fonts to get into testing the horrors of duplicates yet.

I did just enable Source Code through Adobe fonts. It didn't show up until I relaunched AE (which I thought wasn't necessary). But on relaunch a second 'Source Code Pro' allFonts entry did appear with the new styles. And they do show as separate entries in AE's font menu. I'm not seeing anything with appended spaces.

Adding or removing 'Source Code Pro' to MRU or favourites does apply it to both instances, which I guess is what you were getting at with familyNames being an imperfect solution. I like the simplicity of the current solution, but yes it does mean a round trip from and to AE's font menu will munge that information with regard to duplicates.

I guess there could be cases where someone has duplicates and purposefully favourites the specific ones they want, that wouldn't be best pleased when my script instantly wrecks their careful organisation, or fills their 14 MRU slots with duplicates. Another 'how important are edge cases?' situation.

On a separate note, there seems to be some crazy bug in the big Adobe 'font with samples' menu currently where styles multiply every time you look at them. So that's fun! And I also learnt that the Preview Size in the Type prefs does in fact work, you just need to restart for that to change. I only even found that because I was looking for the MRU max pref, neither of which are in the Character panel side menu where you might expect them.

[Paul Tuersley]

Another quick thought. I don't know what your 'yuck!' alternate entry point for reading/writing mru/favorites accurately was, but maybe an alternate would be to supply an array of fontIDs instead of family names? 

Is the first fontID on any allFonts instance a fixed point in a single AE session that could identify the family? I'm already storing my own version of allFonts and would think I could supply or reconcile an array of fontIDs. 

Even better, AE supplies me an array of both [familyName, one of the fontIDs] for an easy lookup and I can supply AE just an array of fontIDs.

[Douglas_Waterfall]

Alas, the UI only wants a Family Name and so ALL the styles/faces are considered to be part of the favorite.

Source Code Pro should automatically show up without relaunching. Did you close and reopen the Char Panel?

As for trailing spaces in the Favorite Family Name - you would not see it in the UI (it is a space) but I expect the the Favorities will have one. Select them both and read back the list - the second one in sort order ought to have one I think.

Douglas Waterfall

After Effects Engineering

[Paul Tuersley]

Alas, the UI only wants a Family Name and so ALL the styles/faces are considered to be part of the favorite.

I realise we're only talking about identifying family instances not styles, but just thought that might be a way to actually identify a specific family instance. But if there's no way to even interact with the font UI with anything more accurate than family name then I guess we just accept the round trip duplicate issue when syncing. Maybe we could even have figured it out with an array of menu indexes if they tallied in a consistent way with allFonts at that moment.

I tried having only one Source Code Pro favorited in the font menu and found on restart they both were so I see that issue is built-in. It doesn't seem to get confused by preserving MRU without duplicates though.

for trailing spaces in the Favorite Family Name - you would not see it in the UI (it is a space) but I expect the the Favorities will have one. Select them both and read back the list - the second one in sort order ought to have one I think.

This is what I get back from AE after I've manually used the Character panel to get the dupe fonts into the top slots.
favs = *Source Code Pro*Source Code Pro*
mru = *Source Code Pro *Source Code Pro*

There's no extra space in favourites but there is in MRU. Is that why MRU preserves itself on relaunch but Favorites doesn't?

If the lack of it on Favorites is an error, and this will actually be consistently present for duplicate family entries, could we deduce which specific family instance is meant based on how many spaces are added and even feed that back to AE with spaces intact and understood?

Even if the order wasn't guarantee to be the current allFonts order, perhaps the fontID ranges inside each instance would reveal the original order the family instances were created and so which one would have x number of spaces?

Source Code Pro should automatically show up without relaunching. Did you close and reopen the Char Panel?

I tried using CC to remove Source Code Pro, then collapsed/uncollapsed the Character panel and it still showed two entries. I tried creating a comp and text layer to see what it'd do with this potentially unknown now missing font and got an endlessly repeating After Effects (Beta) warning: Unknown Exception that required a force quit.

I relaunched, tried also removing Source Sans Pro using CC and that did seem to disappear without prompting. I then used CC to enable Source Sans Pro but closing and reopening the Character panel didn't cause it to appear. I relaunched and it was now in the font list.

Tried removing again using CC, it was still in font list this time, selected it, clicked with Text tool in comp and got repeating Unknown Exception error.

[Douglas_Waterfall]

Thanks for pursuing this - it will save me a bit of time when I return to my desk.

Unfortunately the only thing which is persisted IS the string, no other data. 

The old UI code is not prepared to have duplicate Families and the trailing space is just a dodge so it will allow it, but you see the limitations with the mru/fav.

Favorites is kind of crude, imho, because one might not want the whole font, and with some fonts having many styles it can still be a tall list.

As for Source Code Pro, as I mentioned AE ships with a special instance of this to support the expressions editor. It is a different font the. Adobe Fonts has, but they share the same PostScript name - thus the duplication. So you should never be able to remove all references to Source Code Pro.

Sounds like there are issues with transitioning these - it should not be crashing and I will look into that.

Douglas Waterfall

After Effects Engineering

[Paul Tuersley]

I don't mind favorites being family only. I feel having to manage style favorites would be too fine grained and probably lead to confusion.

For favorites and MRUs, if all duplicate families did have spaces at the end, and each subsequent duplicate gets +1 additional space, then I can't help but think that might be the extra info I need to identify specific family instances and preserve them in a roundtrip to and from AE. It just depends how consistent that extra space hack is and whether AE will recognise them when given back inside the same session.

[Douglas_Waterfall]

Duplicates are a hassle, but probably not that common - but it is worth it to think about it.

The UI is built based on the sort order so duplicates in terms of Family Name is determined by the order the UI  finds the families. First duplicate gets one trailing space, second gets two, etc.

The favorites list is a just loaded into the UI and matched against these entries - so there is no guarantee that it always points to the same family instance.

Now, if you are going to manage your own list, you could figure out what family is being referenced by the favorite and gather some more information with which to identify it - technology and writingScripts[0] would be good ideas. Then you remember that, and when it comes time to build the favorites from your list you go find the fonts in the big list and then see what nTh duplicate it is. With that, you know how many trailing spaces to add.

Yuck.

Douglas Waterfall

After Effects Engineering

[Paul Tuersley]

Yuck indeed. It's the kind of thing I might do in my code, but not what I'd expect from an AE scripting API! I guess a side effect of dealing with an Adobe wide technology in the font menu. And being an undocumented quirk I imagine the danger of it changing in future releases is quite high.

- I've been able to successfully identify the specific duplicate family instances using the spaces at the end after grabbing the app.fonts.mruFontFamilyList array.

- AE does not correctly add MRU to those duplicate instances when you write back to mruFontFamilyList. It fails to do anything with the array item with the space on the end. It's impossible to tell AE to MRU a duplicate family instance currently. A basic example, the following script will remove any duplicate families from the current MRU:
app.fonts.mruFontFamilyList = app.fonts.mruFontFamilyList;

- app.fonts.favoriteFontFamilyList doesn't currently even supply duplicates with spaces. You just get multiple copies of the family name without any spaces.

It seems you're relying on this between AE launches too, as it suffers all the same issues. An AE restart will lose any MRU entries that were duplicates because it's unable to recognise its own system of added spaces. And for favorites, if even one of a duplicate family was favorited then on relaunch all will be favorited because it has no concept of spaces at all. At least this is what seems to be going on.

[Douglas_Waterfall]

@Paul Tuersley I am back from my break and looking into this again.

Without having the code in front of me at the time...it is possible I may have thought you were a bit crazy...

Ah, but no more!

I can reproduce the favorites behavior as well - indeed I mislead you (I was guessing from afar) about the way we handle duplicate familes in the UI (more on that in a bit). When you mark a favorite, we ask the font for its family name, and just save that.

So in this case with duplicate fonts which share the same family...they all report (and respond) to the same name. You've hit the limit of our precision there. In theory we could store additional information in the preferences to differentiate between the duplicates, but we'd need to be careful about versioning...hmm.

We should not be adding duplicates to the list though - I had code which claims to not allow that so something confusing here. I will sort that out.

As for the MRU, following your note above it seems that IS emitting the trailing spaces, where the favorites do not. I will sort that out as well.

Thanks for reporting this in detail - very helpful to me.

Douglas Waterfall

After Effects Engineering

[Douglas_Waterfall]

@Paul Tuersley A fix/change to the handling of favorites and mru is in Beta build 24.5.0 (31).

Note that the UI only lazily updates itself and so that can lead to confusion when you are doing close testing as you have been doing - you can select a favorite, and only one will appear. But then you restart (or cause the UI to regenerate) and then both will appear. So be alert.

Thanks again for your close testing and reporting your findings. Very helpful.

Douglas Waterfall

After Effects Engineering

[Paul Tuersley]

@Douglas_Waterfall I've been testing this again. Here's what I'm seeing:

- favorites seem like they work as expected. No duplicates listed. Adding or removing the single family entry and passing back to AE causes all instances of a family to be added or removed.

- MRU works a bit differently. AE does pass duplicates (no trailing spaces) in its MRU list to the script. But if it receives a list back it will only act on one of those families, presumably adding the first family it encounters to the MRU.

So for example, receive this from app.fonts.mruFontFamilyList

*Source Code Pro*Source Code Pro*DIN Condensed*Academy Engraved LET*

send it back to AE then read it back and you get:

*Source Code Pro*DIN Condensed*Academy Engraved LET*

And AE's MRU updates so only one of them is still in the list. So this suggests it's impossible for a script to add anything but the first family instance to the list, and any act of writing to MRU will munge the treatment of this family.

I'd think it would be better if it worked the same as favorites, adding all instances to the mru list when it comes to duplicate families.

Darn edge cases!

Testing this I do keep running into the issue where Adobe Fonts don't get added or removed to the Character panel until an AE restart. This isn't just dupe families like Source Code. Font Book works, Creative Cloud or Adobe Fonts webpage don't. And trying to select a family in the Character panel that I've removed but it hasn't acknowledged causes a crash.

After Effects (Beta) error: Error attempting to duplicate a text object. Skipping the text layer. (76 :: 53)

After Effects (Beta) warning: Unknown Exception

After Effects Alert: A copy of you project was saved......Last log message was: < 2307049> <CPanoProjItem> <1> DrawImpl error: 14

Though curiously if I already have an existing text layer with that font when I do the remove, AE seems to be able to cling onto it and let you select within that family without issue.

[Douglas_Waterfall]

@Paul Tuersley Hmm, we make slow progress, thanks for your patient playing with this.

I will re-look at the MRU - I would expect that it would match all of them but perhaps this trailing space scheme affected it. I did look at that though...hmm.

Thanks for the crash report with details - we don't want that at all. I will chase that down.

Re: updating the Character Panel - that has bit me before, in particular if you are using the console and running script snippets from there the Character Panel is NOT updated. That turned out to be a good test case for me as I was doing all this work as it in effect forced the situation where the Character Panel was out of date with the FontServer and it should not be crashing because of it.

Prior to my re-work the Character Panel held magic indexes into a shared table that was changing behind its back and sometimes (more often than you might think) the index pointed to nothing and we would crash. I thought I had resolved all those cases but you've found one more it seems.

One way to force the Character Panel to update is to change the sort order - in the panel menu there is "Show English Font Names" (or something like that) - if you flip that on and off the Character Panel will update itself right away.

Normally of course it updates on the idle task so it all happens automatically - but if you are doing things through scripting and expecting something to happen instantly it can create confusion (it did to me).

Thus I am somewhat skeptical about your claim that fonts are not being recognized until reboot - in particular with fonts synced through the Creative Cloud. Given your description I think it is the Character Panel which is out of date. You can use the app.fonts.allFonts API to see what fonts are actually known to the FontServer and I fully expect that your installed font is going to be there.

Fonts which are installed in the Adobe common Fonts folder are NOT recognized until reboot - but you stated you were having issues with Creative Cloud fonts as well. There is a new Beta API to force the recognition of changes to the Adobe common Fonts folder.

One thing to be aware of with removing fonts - if the font is being used somewhere on a Layer, then what happens is the font becomes a substitute to reflect it is still used somewhere (otherwise it would be tossed away) but the Character Panel will sort it at the bottom of the family list with a bracket around it "[Courier]".

All these little gotchas can make development a bit confusing, the best you can do is observe the changes and not necessarily force them. So removing a font might make it go away, but not exactly when you think it should.

Douglas Waterfall

After Effects Engineering

[Paul Tuersley]

@Douglas_Waterfall here's a screen recording that will hopefully clarify what I'm seeing.

[Paul Tuersley]

@Douglas_Waterfall I was surprised to find favorites and mru aren't working in the release of v24.5, they just return null. Is that expected? I know they aren't perfect in the beta, but they're generally functional. I'd been waiting on the v24.5 release to ship my script, thinking everything text related would then be in place, so I'm in limbo with this.

[Douglas_Waterfall]

@Paul Tuersley I will contact you.

Douglas Waterfall

After Effects Engineeering