Document 26.5 SDK: Guide Suite, parametric mesh layers, StreamSuite7, and Premiere Beta effect metadata

docs/aegps/aegp-details.md

@@ -36,4 +36,4 @@ After Effects computes rotation based on auto-orientation (towards path, or poin
 
 ## Accessing Pixels From Effect Layer Parameters
 
-Use `AEGP_GetNewStreamValue` (in [AEGP_StreamSuite5](aegp-suites.md#aegp_streamsuite5)) to get the layer's `layer_id`, then the new `AEGP_GetLayerFromLayerID` (in [AEGP_LayerSuite9](aegp-suites.md#aegp_layersuite9)) to get the `AEGP_LayerH`.
+Use `AEGP_GetNewStreamValue` (in [AEGP_StreamSuite7](aegp-suites.md#aegp_streamsuite7)) to get the layer's `layer_id`, then the new `AEGP_GetLayerFromLayerID` (in [AEGP_LayerSuite9](aegp-suites.md#aegp_layersuite9)) to get the `AEGP_LayerH`.

docs/aegps/cheating-effect-usage-of-aegp-suites.md

@@ -2,7 +2,7 @@
 
 As soon as we showed developers the initial implementation of AEGP suites, they wanted to "cheat" and use them from within effects. This is certainly possible, but please keep in mind that depending on factors outside the effect API (i.e., any information you get from the AEGP APIs) can lead to trouble. If After Effects thinks an effect has all the information it needs to render, it won't (for example) update its parameters based on changes made through an AEGP function. We're actively working on this dependency issue for future versions, but bear it in mind as you write effects which "masquerade" as AEGPs.
 
-Effects can use some AEGP suites to take advantage of camera and lighting information, as well as the `AEGP_GetLayerParentComp` and `AEGP_GetCompBGColor` functions, from [AEGP_CompSuite11](aegp-suites.md#aegp_compsuite11). This should not be interpreted to mean that effects can use *any* AEGP suite calls. Also, see [Effect UI & Events](../effect-ui-events/effect-ui-events.md) for more information on effects adding keyframes.
+Effects can use some AEGP suites to take advantage of camera and lighting information, as well as the `AEGP_GetLayerParentComp` and `AEGP_GetCompBGColor` functions, from [AEGP_CompSuite13](aegp-suites.md#aegp_compsuite13). This should not be interpreted to mean that effects can use *any* AEGP suite calls. Also, see [Effect UI & Events](../effect-ui-events/effect-ui-events.md) for more information on effects adding keyframes.
 
 [AEGP_PFInterfaceSuite](aegp-suites.md#aegp_pfinterfacesuite1) is the starting point. The functions in this suite allow you to retrieve the AEGP_LayerH for the layer to which the effect is applied, and the AEGP_EffectRefH for the instance of your effect. `AEGP_RegisterWithAEGP` from [AEGP_UtilitySuite6](aegp-suites.md#aegp_utilitysuite6) allows you to get an AEGP_PluginID, which is needed for many AEGP calls.
 

docs/aegps/data-types.md

@@ -45,7 +45,7 @@ Whenever possible, After Effects presents plug-ins with opaque data types, and p
 +----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
 | `AEGP_StreamRefH`          | Any [parameter stream](aegp-suites.md#diving-into-streams) attached to a layer, in a composition.                                                                                   | [AEGP Stream Suite](aegp-suites.md#stream-suite),                               |
 |                            |                                                                                                                                                                                     | [AEGP Dynamic Stream Suite](aegp-suites.md#aegp_dynamicstreamsuite4),           |
-|                            | See the description of `AEGP_GetNewLayerStream` from [AEGP_StreamSuite5](aegp-suites.md#stream-suite) for a full list of stream types.                                              | [AEGP Keyframe Suite](aegp-suites.md#aegp_keyframesuite3)                       |
+|                            | See the description of `AEGP_GetNewLayerStream` from [AEGP_StreamSuite7](aegp-suites.md#stream-suite) for a full list of stream types.                                              | [AEGP Keyframe Suite](aegp-suites.md#aegp_keyframesuite3)                       |
 +----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
 | `AEGP_MaskRefH`            | A mask applied to a layer. An AEGP_MaskRefH is used to access details about the mask stream, not the specific points which constitute the mask.                                     | [AEGP Mask Suite](aegp-suites.md#aegp_masksuite6)                               |
 |                            |                                                                                                                                                                                     |                                                                                 |

docs/artisans/artisan-data-types.md

@@ -648,6 +648,6 @@ We've added the ability for artisans to provide functions After Effects can use
 
 `AEGP_QueryXformGetTransformTime()` and `AEGP_QueryXformGetViewTime()` are both necessary for an artisan to build a representation of the scene to render.
 
-`AEGP_QueryXformGetTransformTime()` gets the time of the transform, which is then passed to `AEGP_GetCompShutterFrameRange()` from [AEGP_CompSuite11](../aegps/aegp-suites.md#aegp_compsuite11).
+`AEGP_QueryXformGetTransformTime()` gets the time of the transform, which is then passed to `AEGP_GetCompShutterFrameRange()` from [AEGP_CompSuite13](../aegps/aegp-suites.md#aegp_compsuite13).
 
 `AEGP_QueryXformGetViewTime()` gets the time of the view, which is used in calling `AEGP_GetLayerToWorldXformFromView()` from [AEGP_LayerSuite9](../aegps/aegp-suites.md#aegp_layersuite9).

docs/effect-details/effect-preview-media.md

@@ -0,0 +1,49 @@
+# Effect Preview Media (Effects Panel)
+
+!!! note
+    These features apply to Premiere Pro Beta only, starting with version 27.0. It does not currently apply to After Effects, though After Effects may adopt it in the future.
+
+Third-party effects can ship their own preview media to be shown in the host's Effects panel: a still thumbnail for the effect grid, and a short video that plays on hover. If you don't provide media, the host falls back to a generic category placeholder.
+
+## Where to put the media
+
+Preview media lives in a folder named `Preview`, and each file is named after your plug-in's binary file title (the plug-in filename without its extension). Because the media is keyed on the binary, all effects contained in a single plug-in share the same preview media.
+
+* **Thumbnail (still):** `<pluginFileTitle>.jpg`
+* **Hover preview (video):** `<pluginFileTitle>.mp4`
+
+For example, a plug-in whose binary is `AcmeGlow` would provide `AcmeGlow.jpg` and `AcmeGlow.mp4`.
+
+### macOS
+
+Place the `Preview` folder inside your plug-in's `.plugin` bundle, under `Contents/Resources`:
+
+```
+<PluginName>.plugin/Contents/Resources/Preview/<pluginFileTitle>.jpg
+<PluginName>.plugin/Contents/Resources/Preview/<pluginFileTitle>.mp4
+```
+
+### Windows
+
+Place the `Preview` folder next to your plug-in's `.aex` binary:
+
+```
+<folder containing the .aex>/Preview/<pluginFileTitle>.jpg
+<folder containing the .aex>/Preview/<pluginFileTitle>.mp4
+```
+
+## Format and size
+
+**Thumbnail (still image):**
+
+* Format: `.jpg`
+* Resolution: 640 x 360
+
+**Hover preview (video):**
+
+* Format: `.mp4`, H.264
+* Resolution: 640 x 360
+* File size: as small as reasonably possible; typical is 400 KB to 1 MB
+* Duration: no upper limit, but typically 4 to 10 seconds
+
+The thumbnail is used for the effect's tile in the grid; the video plays when the user hovers over the tile. If you supply only a `.jpg`, the still is used for the tile and there is no hover video.

docs/history.md

@@ -2,6 +2,7 @@
 
 |  Revision Date   |       Documentor        |                                                                                                                                    Notes                                                                                                                                    |
 | ---------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 2 September 2026 | Jessica McMillan |  26.5 SDK Release <br><br>Added the AEGP Guide Suite (`AEGP_GuideSuite1`/`AEGP_GuideSuite2`) for reading and writing guides - orientation, pixel/percentage positioning, per-guide color, and edge pinning - and the `AEGP_ItemViewSuite2` guide display functions (visible, snap, locked). See [Guides](aegps/aegp-suites.md#guides) for more details. <br><br>Added parametric mesh layers. `AEGP_CompSuite13` adds `AEGP_CreateParametricMeshLayerInComp`, and `AEGP_GetLayerObjectType` can now return `AEGP_ObjectType_3D_PARAMETRIC_MESH`. See [What's New](intro/whats-new.md#whats-new-in-the-265-sdk) for more details. <br><br>`AEGP_StreamSuite` is now at version 7, adding independent get/set of the render stage of a `PF_Param_LAYER` stream. See [AEGP_StreamSuite7](aegps/aegp-suites.md#aegp_streamsuite7) for more details. <br><br> Added `AE_Effect_Search_Keywords` and `AE_Effect_Description` PiPL properties (see [PiPL Resources](intro/pipl-resources.md)), and Effects panel preview media support for third-party effects (see [Effect Preview Media (Effects Panel)](effect-details/effect-preview-media.md)). These features apply to Premiere Pro Beta only (from version 27.0). |
 | 8 Sep 2025 | Pablo Colapinto | 25.6 SDK Release - AE SDK supports building effects for Windows on Arm Natively. Please see the [Windows on Arm Support](intro/windows-on-arm-support.md) section for more information. |
 | 24 Feb 2025       | Sean Jenkin          | 25.2 SDK Release - AEGP_GetLayerObjectType can now return AEGP_ObjectType_3D_MODEL if the object type is a 3D model |
 | 5 May 2023       | Jason Bartell           | Update Color Settings suite to AEGP_ColorSettingsSuite5 with new OCIO calls, and added URL property to the PiPL. See [AEGP_ColorSettingsSuite5](aegps/aegp-suites.md#aegp_colorsettingssuite5) and [PiPL Resources](intro/pipl-resources.md) respectively for more details. |

docs/intro/pipl-resources.md

@@ -35,6 +35,46 @@ In the interest of cross-platform compatibility, use a single .r file for both m
 +-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | AE_Effect_Support_URL               | **New in AE 23.5!** URL for the effect. Shown in the Effects Manager. A user might click the link for more information about the effect or to find a newer version.                                                                                                                                              |
 +-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| AE_Effect_Search_Keywords           | **New in the 26.5 SDK (Premiere Pro Beta 27.0 only).** Locale-keyed JSON of search terms for the Effects panel search, e.g. `{"en_US": ["glow"], "es_ES": ["resplandor"]}`. Searchable via the English (`en_US`) and the user's current locale. Malformed JSON is ignored.                                       |
++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| AE_Effect_Description               | **New in the 26.5 SDK (Premiere Pro Beta 27.0 only).** Short description of the effect, shown in the Effects Manager. Authored as a plain string; use ASCII where possible, as non-ASCII in a PiPL resource uses the system code page.                                                                           |
++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+---
+
+## Search Keywords And Description
+
+!!! note
+    These features apply to Premiere Pro Beta only, starting with version 27.0. It does not currently apply to After Effects, though After Effects may adopt it in the future.
+
+You can help users find your effect and understand what it does by declaring search keywords and a description.
+
+* `AE_Effect_Search_Keywords` are matched by the Effects panel search field, so users can find your effect by concepts and synonyms, not just its name.
+* `AE_Effect_Description` is a short summary shown alongside your effect in the Effects Manager.
+
+Search keywords are authored as a JSON string keyed by locale. Each key is a locale code and each value is an array of keyword strings. Your effect is searchable using both the English (`en_US`) keywords and the keywords for the user's current locale, so always include an `en_US` entry and add localized keywords for whichever additional locales you want to support. If the JSON is malformed, the keywords are ignored.
+
+Add both properties to your effect's PiPL, alongside the existing entries:
+
+```c
+AE_Effect_Search_Keywords {
+    "{\"en_US\": [\"glow\", \"bloom\", \"halation\"], \"es_ES\": [\"resplandor\"]}"
+},
+AE_Effect_Description {
+    "Adds a soft glow around bright areas of the image."
+},
+```
+
+On macOS the PiPL is compiled with Apple's `Rez`, which limits each source line to 1023 bytes. If your keyword JSON is long, split it across adjacent string literals — `Rez` joins them into one string, so the compiled result is identical:
+
+```c
+AE_Effect_Search_Keywords {
+    "{\"en_US\": [\"glow\", \"bloom\"], "
+    "\"es_ES\": [\"resplandor\"]}"
+},
+```
+
+Alternatively, if you register your effect from code rather than via a PiPL resource, supply the same two values through the `PF_REGISTER_EFFECT_EXT3` macro (defined in `entry.h`), which uses version 3 of the plug-in entry point and takes `SEARCH_KEYWORDS` and `EFFECT_DESCRIPTION` as its final two arguments.
 
 ---
 

docs/intro/sample-projects.md

@@ -152,6 +152,9 @@ Note that this Windows path is only recommended for development purposes. Window
 
 In Xcode, you can set this path once for the projects in the Xcode File > Project Settings > Advanced. Under *Build Location* choose *Custom: Absolute*, and fill in the path.
 
+!!! warning
+    On macOS, use the per-user `~/Library` path above, which needs no elevated privileges. Don't point the Build Location at the system `/Library/Application Support/Adobe/...` folder: it is owned by `root`, so an unprivileged build fails with a confusing Xcode "Could not compute dependency graph / mktemp failed" error rather than a clear permissions message. Building with `sudo` to work around this is not recommended either, as it leaves root-owned build artifacts that break later rebuilds and cleans. If you specifically need the plug-in in the system folder, build normally and then copy the finished `.plugin` there with an elevated copy (for example `sudo cp -R`).
+
 In Visual Studio, for convenience, we have specified the output path for all sample projects using the environment variable AE_PLUGIN_BUILD_DIR. You'll need to set this as a user environment variable for your system. On Windows 7, right-click *My Computer* > *Properties* > and in the left sidebar choose *Advanced System Settings*. In the new dialog, hit the *Environment Variables* button. In the User variables area, create a New variable named AE_PLUGIN_BUILD_DIR, and with the path described above. Log out of Windows and log back in so that the variable will be set.
 
 Alternatively, you can set output path for each project individually in Visual Studio by right-clicking a project in the Solution Explorer, choosing Properties, and then in Configuration Properties > Linker > General, set the Output File.