Skip to content

ws_stub

Stub handling connection from server to client. Used anywhere solution is calling client methods.

AEItem

Bases: object

Object denoting Item in AE. Each item is created in AE by any Loader, but contains same fields, which are being used in later processing.

Source code in client/ayon_aftereffects/api/ws_stub.py
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
@attr.s
class AEItem(object):
    """
        Object denoting Item in AE. Each item is created in AE by any Loader,
        but contains same fields, which are being used in later processing.
    """
    # metadata
    id = attr.ib()  # id created by AE, could be used for querying
    name = attr.ib()  # name of item
    item_type = attr.ib(default=None)  # item type (footage, folder, comp)
    # all imported elements, single for
    # regular image, array for Backgrounds
    members = attr.ib(factory=list)
    frameStart = attr.ib(default=None)
    framesDuration = attr.ib(default=None)
    frameRate = attr.ib(default=None)
    file_name = attr.ib(default=None)
    instance_id = attr.ib(default=None)  # New Publisher
    width = attr.ib(default=None)
    height = attr.ib(default=None)
    is_placeholder = attr.ib(default=False)
    uuid = attr.ib(default=False)
    path = attr.ib(default=False)  # path to FootageItem to validate
    # list of composition Footage is in
    containing_comps = attr.ib(factory=list)

AfterEffectsServerStub

Stub for calling function on client (After Effects js) side.

Expects that client is already connected (started when AYON menu is opened)

'self.websocketserver.call' is used as async wrapper

Source code in client/ayon_aftereffects/api/ws_stub.py
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
class AfterEffectsServerStub():
    """Stub for calling function on client (After Effects js) side.

    Expects that client is already connected (started when AYON menu is opened)

    'self.websocketserver.call' is used as async wrapper
    """
    PUBLISH_ICON = '\u2117 '
    LOADED_ICON = '\u25bc'

    def __init__(self):
        self.websocketserver = WebServerTool.get_instance()
        self.client = self.get_client()
        self.log = logging.getLogger(self.__class__.__name__)

    @staticmethod
    def get_client():
        """
            Return first connected client to WebSocket
            TODO implement selection by Route
        :return: <WebSocketAsync> client
        """
        clients = WebSocketAsync.get_clients()
        client = None
        if len(clients) > 0:
            key = list(clients.keys())[0]
            client = clients.get(key)

        return client

    def open(self, path):
        """
            Open file located at 'path' (local).
        Args:
            path(string): file path locally
        Returns: None
        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.open', path=path))

        return self._handle_return(res)

    def get_metadata(self):
        """
            Get complete stored JSON with metadata from AE.Metadata.Label
            field.

            It contains containers loaded by any Loader OR instances created
            by Creator.

        Returns:
            (list)
        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.get_metadata'))
        metadata = self._handle_return(res)

        return metadata or []

    def read(self, item, layers_meta=None):
        """
            Parses item metadata from Label field of active document.
            Used as filter to pick metadata for specific 'item' only.

        Args:
            item (AEItem): pulled info from AE
            layers_meta (dict): full list from Headline
                (load and inject for better performance in loops)
        Returns:
            (dict):
        """
        if layers_meta is None:
            layers_meta = self.get_metadata()
        for item_meta in layers_meta:
            if 'container' in item_meta.get('id') and \
                    str(item.id) == str(item_meta.get('members')[0]):
                return item_meta

        self.log.debug(f"Couldn't find layer metadata for item: {item}")

    def imprint(self, item_id, data, all_items=None, items_meta=None):
        """
            Save item metadata to Label field of metadata of active document
        Args:
            item_id (int|str): id of FootageItem or instance_id for workfiles
            data(string): json representation for single layer
            all_items (list of item): for performance, could be
                injected for usage in loop, if not, single call will be
                triggered
            items_meta(string): json representation from Headline
                           (for performance - provide only if imprint is in
                           loop - value should be same)
        Returns: None
        """
        if not items_meta:
            items_meta = self.get_metadata()

        result_meta = []
        # fix existing
        is_new = True

        for item_meta in items_meta:
            if ((item_meta.get('members') and
                    str(item_id) == str(item_meta.get('members')[0])) or
                    item_meta.get("instance_id") == item_id):
                is_new = False
                if data:
                    item_meta.update(data)
                    result_meta.append(item_meta)
            else:
                result_meta.append(item_meta)

        if is_new:
            result_meta.append(data)

        # Ensure only valid ids are stored.
        if not all_items:
            # loaders create FootageItem now
            all_items = self.get_items(comps=True,
                                       folders=True,
                                       footages=True)
        item_ids = [int(item.id) for item in all_items]
        cleaned_data = []
        for meta in result_meta:
            # do not added instance with nonexistend item id
            if meta.get("members"):
                if int(meta["members"][0]) not in item_ids:
                    continue

            cleaned_data.append(meta)

        payload = json.dumps(cleaned_data, indent=4)

        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.imprint',
                                         payload=payload))
        return self._handle_return(res)

    def get_active_document_full_name(self):
        """
            Returns absolute path of active document via ws call
        Returns(string): file name
        """
        res = self.websocketserver.call(self.client.call(
            'AfterEffects.get_active_document_full_name'))

        return self._handle_return(res)

    def get_active_document_name(self):
        """
            Returns just a name of active document via ws call
        Returns(string): file name
        """
        res = self.websocketserver.call(self.client.call(
            'AfterEffects.get_active_document_name'))

        return self._handle_return(res)

    def get_items(self, comps, folders=False, footages=False):
        """
            Get all items from Project panel according to arguments.
            There are multiple different types:
                CompItem (could have multiple layers - source for Creator,
                    will be rendered)
                FolderItem (collection type, currently used for Background
                    loading)
                FootageItem (imported file - created by Loader)
        Args:
            comps (bool): return CompItems
            folders (bool): return FolderItem
            footages (bool: return FootageItem

        Returns:
            (list) of namedtuples
        """
        res = self.websocketserver.call(
            self.client.call('AfterEffects.get_items',
                             comps=comps,
                             folders=folders,
                             footages=footages)
              )
        return self._to_records(self._handle_return(res))

    def select_items(self, items):
        """
            Select items in Project list
        Args:
            items (list): of int item ids
        """
        self.websocketserver.call(
            self.client.call('AfterEffects.select_items', items=items))


    def get_selected_items(self, comps, folders=False, footages=False):
        """
            Same as get_items but using selected items only
        Args:
            comps (bool): return CompItems
            folders (bool): return FolderItem
            footages (bool: return FootageItem

        Returns:
            (list) of namedtuples

        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.get_selected_items',
                                         comps=comps,
                                         folders=folders,
                                         footages=footages)
                                        )
        return self._to_records(self._handle_return(res))

    def add_item(self, name, item_type):
        """
            Adds either composition or folder to project item list.

            Args:
                name (str)
                item_type (str): COMP|FOLDER
        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.add_item',
                                         name=name,
                                         item_type=item_type))

        return self._handle_return(res)

    def get_item(self, item_id):
        """
            Returns metadata for particular 'item_id' or None

            Args:
                item_id (int, or string)
        """
        for item in self.get_items(True, True, True):
            if str(item.id) == str(item_id):
                return item

        return None

    def import_file(self, path, item_name, import_options=None):
        """
            Imports file as a FootageItem. Used in Loader
        Args:
            path (string): absolute path for asset file
            item_name (string): label for created FootageItem
            import_options (dict): different files (img vs psd) need different
                config

        """
        res = self.websocketserver.call(
            self.client.call('AfterEffects.import_file',
                             path=path,
                             item_name=item_name,
                             import_options=import_options)
            )
        records = self._to_records(self._handle_return(res))
        if records:
            return records.pop()

    def replace_item(self, item_id, path, item_name):
        """ Replace FootageItem with new file

            Args:
                item_id (int):
                path (string):absolute path
                item_name (string): label on item in Project list

        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.replace_item',
                                         item_id=item_id,
                                         path=path, item_name=item_name))

        return self._handle_return(res)

    def rename_item(self, item_id, item_name):
        """ Replace item with item_name

            Args:
                item_id (int):
                item_name (string): label on item in Project list

        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.rename_item',
                                         item_id=item_id,
                                         item_name=item_name))

        return self._handle_return(res)

    def delete_item(self, item_id):
        """ Deletes *Item in a file
            Args:
                item_id (int):

        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.delete_item',
                                         item_id=item_id))

        return self._handle_return(res)

    def remove_instance(self, instance_id, metadata=None):
        """
            Removes instance with 'instance_id' from file's metadata and
            saves them.

            Keep matching item in file though.

            Args:
                instance_id(string): instance id
        """
        cleaned_data = []

        if metadata is None:
            metadata = self.get_metadata()

        for instance in metadata:
            inst_id = instance.get("instance_id") or instance.get("uuid")
            if inst_id != instance_id:
                cleaned_data.append(instance)

        payload = json.dumps(cleaned_data, indent=4)
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.imprint',
                                         payload=payload))

        return self._handle_return(res)

    def is_saved(self):
        # TODO
        return True

    def set_label_color(self, item_id, color_idx):
        """
            Used for highlight additional information in Project panel.
            Green color is loaded asset, blue is created asset
        Args:
            item_id (int):
            color_idx (int): 0-16 Label colors from AE Project view
        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.set_label_color',
                                         item_id=item_id,
                                         color_idx=color_idx))

        return self._handle_return(res)

    def get_comp_properties(self, comp_id):
        """ Get composition information for render purposes

            Returns startFrame, frameDuration, fps, width, height.

            Args:
                comp_id (int):

            Returns:
                (AEItem)

        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.get_comp_properties',
                                         item_id=comp_id
                                         ))

        records = self._to_records(self._handle_return(res))
        if records:
            return records.pop()

    def set_comp_properties(self, comp_id, start, duration, frame_rate,
                            width, height):
        """
            Set work area to predefined values (from Ftrack).
            Work area directs what gets rendered.
            Beware of rounding, AE expects seconds, not frames directly.

        Args:
            comp_id (int):
            start (int): workAreaStart in frames
            duration (int): in frames
            frame_rate (float): frames in seconds
            width (int): resolution width
            height (int): resolution height
        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.set_comp_properties',
                                         item_id=comp_id,
                                         start=start,
                                         duration=duration,
                                         frame_rate=frame_rate,
                                         width=width,
                                         height=height))
        return self._handle_return(res)

    def save(self):
        """
            Saves active document
        Returns: None
        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.save'))

        return self._handle_return(res)

    def saveAs(self, project_path, as_copy):
        """
            Saves active project to aep (copy) or png or jpg
        Args:
            project_path(string): full local path
            as_copy: <boolean>
        Returns: None
        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.saveAs',
                                         image_path=project_path,
                                         as_copy=as_copy))

        return self._handle_return(res)

    def get_render_info(self, comp_id):
        """ Get render queue info for render purposes

            Returns:
               (list) of (AEItem): with 'file_name' field
        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.get_render_info',
                                         comp_id=comp_id))

        records = self._to_records(self._handle_return(res))
        return records

    def get_audio_url(self, item_id):
        """ Get audio layer absolute url for comp

            Args:
                item_id (int): composition id
            Returns:
                (str): absolute path url
        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.get_audio_url',
                                         item_id=item_id))

        return self._handle_return(res)

    def import_background(self, comp_id, comp_name, files):
        """
            Imports backgrounds images to existing or new composition.

            If comp_id is not provided, new composition is created, basic
            values (width, heights, frameRatio) takes from first imported
            image.

            All images from background json are imported as a FootageItem and
            separate layer is created for each of them under composition.

            Order of imported 'files' is important.

            Args:
                comp_id (int): id of existing composition (null if new)
                comp_name (str): used when new composition
                files (list): list of absolute paths to import and
                add as layers

            Returns:
                (AEItem): object with id of created folder, all imported images
        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.import_background',
                                         comp_id=comp_id,
                                         comp_name=comp_name,
                                         files=files))

        records = self._to_records(self._handle_return(res))
        if records:
            return records.pop()

    def reload_background(self, comp_id, comp_name, files):
        """
            Reloads backgrounds images to existing composition.

            It actually deletes complete folder with imported images and
            created composition for safety.

            Args:
                comp_id (int): id of existing composition to be overwritten
                comp_name (str): new name of composition (could be same as old
                    if version up only)
                files (list): list of absolute paths to import and
                    add as layers
            Returns:
                (AEItem): object with id of created folder, all imported images
        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.reload_background',
                                         comp_id=comp_id,
                                         comp_name=comp_name,
                                         files=files))

        records = self._to_records(self._handle_return(res))
        if records:
            return records.pop()

    def add_item_as_layer(self, comp_id, item_id):
        """
            Adds already imported FootageItem ('item_id') as a new
            layer to composition ('comp_id').

            Args:
                comp_id (int): id of target composition
                item_id (int): FootageItem.id
                comp already found previously
        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.add_item_as_layer',
                                         comp_id=comp_id,
                                         item_id=item_id))

        records = self._to_records(self._handle_return(res))
        if records:
            return records.pop()

    def add_item_instead_placeholder(self, placeholder_item_id, item_id):
        """
            Adds item_id to layers where plaeholder_item_id is present.

            1 placeholder could result in multiple loaded containers (eg items)

            Args:
                placeholder_item_id (int): id of placeholder item
                item_id (int): loaded FootageItem id
        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.add_item_instead_placeholder',  # noqa
                                         placeholder_item_id=placeholder_item_id,  # noqa
                                         item_id=item_id))

        return self._handle_return(res)

    def add_placeholder(self, name, width, height, fps, duration):
        """
            Adds new FootageItem as a placeholder for workfile builder

            Placeholder requires width etc, currently probably only hardcoded
            values.

            Args:
                name (str)
                width (int)
                height (int)
                fps (float)
                duration (int)
        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.add_placeholder',
                                         name=name,
                                         width=width,
                                         height=height,
                                         fps=fps,
                                         duration=duration))

        return self._handle_return(res)

    def render(self, folder_url, comp_id):
        """
            Render all renderqueueitem to 'folder_url'
        Args:
            folder_url(string): local folder path for collecting
        Returns: None
        """
        res = self.websocketserver.call(self.client.call
                                        ('AfterEffects.render',
                                         folder_url=folder_url,
                                         comp_id=comp_id))
        return self._handle_return(res)

    def get_extension_version(self):
        """Returns version number of installed extension."""
        res = self.websocketserver.call(self.client.call(
            'AfterEffects.get_extension_version'))

        return self._handle_return(res)

    def get_app_version(self):
        """Returns version number of installed application (17.5...)."""
        res = self.websocketserver.call(self.client.call(
            'AfterEffects.get_app_version'))

        return self._handle_return(res)

    def close(self):
        res = self.websocketserver.call(self.client.call('AfterEffects.close'))

        return self._handle_return(res)

    def print_msg(self, msg):
        """Triggers Javascript alert dialog."""
        self.websocketserver.call(self.client.call
                                  ('AfterEffects.print_msg',
                                   msg=msg))

    def _handle_return(self, res):
        """Wraps return, throws ValueError if 'error' key is present."""
        if res and isinstance(res, str) and res != "undefined":
            try:
                parsed = json.loads(res)
            except json.decoder.JSONDecodeError:
                raise ValueError("Received broken JSON {}".format(res))

            if not parsed:  # empty list
                return parsed

            first_item = parsed
            if isinstance(parsed, list):
                first_item = parsed[0]

            if first_item:
                if first_item.get("error"):
                    raise ValueError(first_item["error"])
                # singular values (file name etc)
                if first_item.get("result") is not None:
                    return first_item["result"]
            return parsed  # parsed
        return res

    def _to_records(self, payload):
        """
            Converts string json representation into list of AEItem
            dot notation access to work.
        Returns: <list of AEItem>
            payload(dict): - dictionary from json representation, expected to
                come from _handle_return
        """
        if not payload:
            return []

        if isinstance(payload, str):  # safety fallback
            try:
                payload = json.loads(payload)
            except json.decoder.JSONDecodeError:
                raise ValueError("Received broken JSON {}".format(payload))

        if isinstance(payload, dict):
            payload = [payload]

        ret = []
        # convert to AEItem to use dot donation
        for d in payload:
            if not d:
                continue
            # currently implemented and expected fields
            item = AEItem(d.get('id'),
                          d.get('name'),
                          d.get('type'),
                          d.get('members'),
                          d.get('frameStart'),
                          d.get('framesDuration'),
                          d.get('frameRate'),
                          d.get('file_name'),
                          d.get("instance_id"),
                          d.get("width"),
                          d.get("height"),
                          d.get("is_placeholder"),
                          d.get("uuid"),
                          d.get("path"),
                          d.get("containing_comps"),)

            ret.append(item)
        return ret

add_item(name, item_type)

Adds either composition or folder to project item list.

Parameters:

Name Type Description Default
item_type str

COMP|FOLDER

required
Source code in client/ayon_aftereffects/api/ws_stub.py
259
260
261
262
263
264
265
266
267
268
269
270
271
272
def add_item(self, name, item_type):
    """
        Adds either composition or folder to project item list.

        Args:
            name (str)
            item_type (str): COMP|FOLDER
    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.add_item',
                                     name=name,
                                     item_type=item_type))

    return self._handle_return(res)

add_item_as_layer(comp_id, item_id)

Adds already imported FootageItem ('item_id') as a new layer to composition ('comp_id').

Parameters:

Name Type Description Default
comp_id int

id of target composition

required
item_id int

FootageItem.id

required
Source code in client/ayon_aftereffects/api/ws_stub.py
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
def add_item_as_layer(self, comp_id, item_id):
    """
        Adds already imported FootageItem ('item_id') as a new
        layer to composition ('comp_id').

        Args:
            comp_id (int): id of target composition
            item_id (int): FootageItem.id
            comp already found previously
    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.add_item_as_layer',
                                     comp_id=comp_id,
                                     item_id=item_id))

    records = self._to_records(self._handle_return(res))
    if records:
        return records.pop()

add_item_instead_placeholder(placeholder_item_id, item_id)

Adds item_id to layers where plaeholder_item_id is present.

1 placeholder could result in multiple loaded containers (eg items)

Parameters:

Name Type Description Default
placeholder_item_id int

id of placeholder item

required
item_id int

loaded FootageItem id

required
Source code in client/ayon_aftereffects/api/ws_stub.py
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
def add_item_instead_placeholder(self, placeholder_item_id, item_id):
    """
        Adds item_id to layers where plaeholder_item_id is present.

        1 placeholder could result in multiple loaded containers (eg items)

        Args:
            placeholder_item_id (int): id of placeholder item
            item_id (int): loaded FootageItem id
    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.add_item_instead_placeholder',  # noqa
                                     placeholder_item_id=placeholder_item_id,  # noqa
                                     item_id=item_id))

    return self._handle_return(res)

add_placeholder(name, width, height, fps, duration)

Adds new FootageItem as a placeholder for workfile builder

Placeholder requires width etc, currently probably only hardcoded values.

Source code in client/ayon_aftereffects/api/ws_stub.py
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
def add_placeholder(self, name, width, height, fps, duration):
    """
        Adds new FootageItem as a placeholder for workfile builder

        Placeholder requires width etc, currently probably only hardcoded
        values.

        Args:
            name (str)
            width (int)
            height (int)
            fps (float)
            duration (int)
    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.add_placeholder',
                                     name=name,
                                     width=width,
                                     height=height,
                                     fps=fps,
                                     duration=duration))

    return self._handle_return(res)

delete_item(item_id)

Deletes *Item in a file Args: item_id (int):

Source code in client/ayon_aftereffects/api/ws_stub.py
338
339
340
341
342
343
344
345
346
347
348
def delete_item(self, item_id):
    """ Deletes *Item in a file
        Args:
            item_id (int):

    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.delete_item',
                                     item_id=item_id))

    return self._handle_return(res)

get_active_document_full_name()

Returns absolute path of active document via ws call

Returns(string): file name

Source code in client/ayon_aftereffects/api/ws_stub.py
184
185
186
187
188
189
190
191
192
def get_active_document_full_name(self):
    """
        Returns absolute path of active document via ws call
    Returns(string): file name
    """
    res = self.websocketserver.call(self.client.call(
        'AfterEffects.get_active_document_full_name'))

    return self._handle_return(res)

get_active_document_name()

Returns just a name of active document via ws call

Returns(string): file name

Source code in client/ayon_aftereffects/api/ws_stub.py
194
195
196
197
198
199
200
201
202
def get_active_document_name(self):
    """
        Returns just a name of active document via ws call
    Returns(string): file name
    """
    res = self.websocketserver.call(self.client.call(
        'AfterEffects.get_active_document_name'))

    return self._handle_return(res)

get_app_version()

Returns version number of installed application (17.5...).

Source code in client/ayon_aftereffects/api/ws_stub.py
632
633
634
635
636
637
def get_app_version(self):
    """Returns version number of installed application (17.5...)."""
    res = self.websocketserver.call(self.client.call(
        'AfterEffects.get_app_version'))

    return self._handle_return(res)

get_audio_url(item_id)

Get audio layer absolute url for comp

Parameters:

Name Type Description Default
item_id int

composition id

required

Returns: (str): absolute path url

Source code in client/ayon_aftereffects/api/ws_stub.py
480
481
482
483
484
485
486
487
488
489
490
491
492
def get_audio_url(self, item_id):
    """ Get audio layer absolute url for comp

        Args:
            item_id (int): composition id
        Returns:
            (str): absolute path url
    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.get_audio_url',
                                     item_id=item_id))

    return self._handle_return(res)

get_client() staticmethod

Return first connected client to WebSocket
TODO implement selection by Route

:return: client

Source code in client/ayon_aftereffects/api/ws_stub.py
61
62
63
64
65
66
67
68
69
70
71
72
73
74
@staticmethod
def get_client():
    """
        Return first connected client to WebSocket
        TODO implement selection by Route
    :return: <WebSocketAsync> client
    """
    clients = WebSocketAsync.get_clients()
    client = None
    if len(clients) > 0:
        key = list(clients.keys())[0]
        client = clients.get(key)

    return client

get_comp_properties(comp_id)

Get composition information for render purposes

Returns startFrame, frameDuration, fps, width, height.

Parameters:

Name Type Description Default
comp_id int
required

Returns:

Type Description

(AEItem)

Source code in client/ayon_aftereffects/api/ws_stub.py
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
def get_comp_properties(self, comp_id):
    """ Get composition information for render purposes

        Returns startFrame, frameDuration, fps, width, height.

        Args:
            comp_id (int):

        Returns:
            (AEItem)

    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.get_comp_properties',
                                     item_id=comp_id
                                     ))

    records = self._to_records(self._handle_return(res))
    if records:
        return records.pop()

get_extension_version()

Returns version number of installed extension.

Source code in client/ayon_aftereffects/api/ws_stub.py
625
626
627
628
629
630
def get_extension_version(self):
    """Returns version number of installed extension."""
    res = self.websocketserver.call(self.client.call(
        'AfterEffects.get_extension_version'))

    return self._handle_return(res)

get_item(item_id)

Returns metadata for particular 'item_id' or None

Source code in client/ayon_aftereffects/api/ws_stub.py
274
275
276
277
278
279
280
281
282
283
284
285
def get_item(self, item_id):
    """
        Returns metadata for particular 'item_id' or None

        Args:
            item_id (int, or string)
    """
    for item in self.get_items(True, True, True):
        if str(item.id) == str(item_id):
            return item

    return None

get_items(comps, folders=False, footages=False)

Get all items from Project panel according to arguments.
There are multiple different types:
    CompItem (could have multiple layers - source for Creator,
        will be rendered)
    FolderItem (collection type, currently used for Background
        loading)
    FootageItem (imported file - created by Loader)

Args: comps (bool): return CompItems folders (bool): return FolderItem footages (bool: return FootageItem

Returns:

Type Description

(list) of namedtuples

Source code in client/ayon_aftereffects/api/ws_stub.py
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
def get_items(self, comps, folders=False, footages=False):
    """
        Get all items from Project panel according to arguments.
        There are multiple different types:
            CompItem (could have multiple layers - source for Creator,
                will be rendered)
            FolderItem (collection type, currently used for Background
                loading)
            FootageItem (imported file - created by Loader)
    Args:
        comps (bool): return CompItems
        folders (bool): return FolderItem
        footages (bool: return FootageItem

    Returns:
        (list) of namedtuples
    """
    res = self.websocketserver.call(
        self.client.call('AfterEffects.get_items',
                         comps=comps,
                         folders=folders,
                         footages=footages)
          )
    return self._to_records(self._handle_return(res))

get_metadata()

Get complete stored JSON with metadata from AE.Metadata.Label
field.

It contains containers loaded by any Loader OR instances created
by Creator.

Returns:

Type Description

(list)

Source code in client/ayon_aftereffects/api/ws_stub.py
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def get_metadata(self):
    """
        Get complete stored JSON with metadata from AE.Metadata.Label
        field.

        It contains containers loaded by any Loader OR instances created
        by Creator.

    Returns:
        (list)
    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.get_metadata'))
    metadata = self._handle_return(res)

    return metadata or []

get_render_info(comp_id)

Get render queue info for render purposes

Returns:

Type Description
list) of (AEItem

with 'file_name' field

Source code in client/ayon_aftereffects/api/ws_stub.py
467
468
469
470
471
472
473
474
475
476
477
478
def get_render_info(self, comp_id):
    """ Get render queue info for render purposes

        Returns:
           (list) of (AEItem): with 'file_name' field
    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.get_render_info',
                                     comp_id=comp_id))

    records = self._to_records(self._handle_return(res))
    return records

get_selected_items(comps, folders=False, footages=False)

Same as get_items but using selected items only

Args: comps (bool): return CompItems folders (bool): return FolderItem footages (bool: return FootageItem

Returns:

Type Description

(list) of namedtuples

Source code in client/ayon_aftereffects/api/ws_stub.py
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
def get_selected_items(self, comps, folders=False, footages=False):
    """
        Same as get_items but using selected items only
    Args:
        comps (bool): return CompItems
        folders (bool): return FolderItem
        footages (bool: return FootageItem

    Returns:
        (list) of namedtuples

    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.get_selected_items',
                                     comps=comps,
                                     folders=folders,
                                     footages=footages)
                                    )
    return self._to_records(self._handle_return(res))

import_background(comp_id, comp_name, files)

Imports backgrounds images to existing or new composition.

If comp_id is not provided, new composition is created, basic values (width, heights, frameRatio) takes from first imported image.

All images from background json are imported as a FootageItem and separate layer is created for each of them under composition.

Order of imported 'files' is important.

Parameters:

Name Type Description Default
comp_id int

id of existing composition (null if new)

required
comp_name str

used when new composition

required
files list

list of absolute paths to import and

required

Returns:

Type Description
AEItem

object with id of created folder, all imported images

Source code in client/ayon_aftereffects/api/ws_stub.py
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
def import_background(self, comp_id, comp_name, files):
    """
        Imports backgrounds images to existing or new composition.

        If comp_id is not provided, new composition is created, basic
        values (width, heights, frameRatio) takes from first imported
        image.

        All images from background json are imported as a FootageItem and
        separate layer is created for each of them under composition.

        Order of imported 'files' is important.

        Args:
            comp_id (int): id of existing composition (null if new)
            comp_name (str): used when new composition
            files (list): list of absolute paths to import and
            add as layers

        Returns:
            (AEItem): object with id of created folder, all imported images
    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.import_background',
                                     comp_id=comp_id,
                                     comp_name=comp_name,
                                     files=files))

    records = self._to_records(self._handle_return(res))
    if records:
        return records.pop()

import_file(path, item_name, import_options=None)

Imports file as a FootageItem. Used in Loader

Args: path (string): absolute path for asset file item_name (string): label for created FootageItem import_options (dict): different files (img vs psd) need different config

Source code in client/ayon_aftereffects/api/ws_stub.py
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
def import_file(self, path, item_name, import_options=None):
    """
        Imports file as a FootageItem. Used in Loader
    Args:
        path (string): absolute path for asset file
        item_name (string): label for created FootageItem
        import_options (dict): different files (img vs psd) need different
            config

    """
    res = self.websocketserver.call(
        self.client.call('AfterEffects.import_file',
                         path=path,
                         item_name=item_name,
                         import_options=import_options)
        )
    records = self._to_records(self._handle_return(res))
    if records:
        return records.pop()

imprint(item_id, data, all_items=None, items_meta=None)

Save item metadata to Label field of metadata of active document

Args: item_id (int|str): id of FootageItem or instance_id for workfiles data(string): json representation for single layer all_items (list of item): for performance, could be injected for usage in loop, if not, single call will be triggered items_meta(string): json representation from Headline (for performance - provide only if imprint is in loop - value should be same) Returns: None

Source code in client/ayon_aftereffects/api/ws_stub.py
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
def imprint(self, item_id, data, all_items=None, items_meta=None):
    """
        Save item metadata to Label field of metadata of active document
    Args:
        item_id (int|str): id of FootageItem or instance_id for workfiles
        data(string): json representation for single layer
        all_items (list of item): for performance, could be
            injected for usage in loop, if not, single call will be
            triggered
        items_meta(string): json representation from Headline
                       (for performance - provide only if imprint is in
                       loop - value should be same)
    Returns: None
    """
    if not items_meta:
        items_meta = self.get_metadata()

    result_meta = []
    # fix existing
    is_new = True

    for item_meta in items_meta:
        if ((item_meta.get('members') and
                str(item_id) == str(item_meta.get('members')[0])) or
                item_meta.get("instance_id") == item_id):
            is_new = False
            if data:
                item_meta.update(data)
                result_meta.append(item_meta)
        else:
            result_meta.append(item_meta)

    if is_new:
        result_meta.append(data)

    # Ensure only valid ids are stored.
    if not all_items:
        # loaders create FootageItem now
        all_items = self.get_items(comps=True,
                                   folders=True,
                                   footages=True)
    item_ids = [int(item.id) for item in all_items]
    cleaned_data = []
    for meta in result_meta:
        # do not added instance with nonexistend item id
        if meta.get("members"):
            if int(meta["members"][0]) not in item_ids:
                continue

        cleaned_data.append(meta)

    payload = json.dumps(cleaned_data, indent=4)

    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.imprint',
                                     payload=payload))
    return self._handle_return(res)

open(path)

Open file located at 'path' (local).

Args: path(string): file path locally Returns: None

Source code in client/ayon_aftereffects/api/ws_stub.py
76
77
78
79
80
81
82
83
84
85
86
def open(self, path):
    """
        Open file located at 'path' (local).
    Args:
        path(string): file path locally
    Returns: None
    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.open', path=path))

    return self._handle_return(res)

print_msg(msg)

Triggers Javascript alert dialog.

Source code in client/ayon_aftereffects/api/ws_stub.py
644
645
646
647
648
def print_msg(self, msg):
    """Triggers Javascript alert dialog."""
    self.websocketserver.call(self.client.call
                              ('AfterEffects.print_msg',
                               msg=msg))

read(item, layers_meta=None)

Parses item metadata from Label field of active document.
Used as filter to pick metadata for specific 'item' only.

Parameters:

Name Type Description Default
item AEItem

pulled info from AE

required
layers_meta dict

full list from Headline (load and inject for better performance in loops)

None

Returns: (dict):

Source code in client/ayon_aftereffects/api/ws_stub.py
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
def read(self, item, layers_meta=None):
    """
        Parses item metadata from Label field of active document.
        Used as filter to pick metadata for specific 'item' only.

    Args:
        item (AEItem): pulled info from AE
        layers_meta (dict): full list from Headline
            (load and inject for better performance in loops)
    Returns:
        (dict):
    """
    if layers_meta is None:
        layers_meta = self.get_metadata()
    for item_meta in layers_meta:
        if 'container' in item_meta.get('id') and \
                str(item.id) == str(item_meta.get('members')[0]):
            return item_meta

    self.log.debug(f"Couldn't find layer metadata for item: {item}")

reload_background(comp_id, comp_name, files)

Reloads backgrounds images to existing composition.

It actually deletes complete folder with imported images and created composition for safety.

Parameters:

Name Type Description Default
comp_id int

id of existing composition to be overwritten

required
comp_name str

new name of composition (could be same as old if version up only)

required
files list

list of absolute paths to import and add as layers

required

Returns: (AEItem): object with id of created folder, all imported images

Source code in client/ayon_aftereffects/api/ws_stub.py
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
def reload_background(self, comp_id, comp_name, files):
    """
        Reloads backgrounds images to existing composition.

        It actually deletes complete folder with imported images and
        created composition for safety.

        Args:
            comp_id (int): id of existing composition to be overwritten
            comp_name (str): new name of composition (could be same as old
                if version up only)
            files (list): list of absolute paths to import and
                add as layers
        Returns:
            (AEItem): object with id of created folder, all imported images
    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.reload_background',
                                     comp_id=comp_id,
                                     comp_name=comp_name,
                                     files=files))

    records = self._to_records(self._handle_return(res))
    if records:
        return records.pop()

remove_instance(instance_id, metadata=None)

Removes instance with 'instance_id' from file's metadata and saves them.

Keep matching item in file though.

Parameters:

Name Type Description Default
instance_id(string)

instance id

required
Source code in client/ayon_aftereffects/api/ws_stub.py
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
def remove_instance(self, instance_id, metadata=None):
    """
        Removes instance with 'instance_id' from file's metadata and
        saves them.

        Keep matching item in file though.

        Args:
            instance_id(string): instance id
    """
    cleaned_data = []

    if metadata is None:
        metadata = self.get_metadata()

    for instance in metadata:
        inst_id = instance.get("instance_id") or instance.get("uuid")
        if inst_id != instance_id:
            cleaned_data.append(instance)

    payload = json.dumps(cleaned_data, indent=4)
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.imprint',
                                     payload=payload))

    return self._handle_return(res)

rename_item(item_id, item_name)

Replace item with item_name

Parameters:

Name Type Description Default
item_id int
required
item_name string

label on item in Project list

required
Source code in client/ayon_aftereffects/api/ws_stub.py
323
324
325
326
327
328
329
330
331
332
333
334
335
336
def rename_item(self, item_id, item_name):
    """ Replace item with item_name

        Args:
            item_id (int):
            item_name (string): label on item in Project list

    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.rename_item',
                                     item_id=item_id,
                                     item_name=item_name))

    return self._handle_return(res)

render(folder_url, comp_id)

Render all renderqueueitem to 'folder_url'

Args: folder_url(string): local folder path for collecting Returns: None

Source code in client/ayon_aftereffects/api/ws_stub.py
612
613
614
615
616
617
618
619
620
621
622
623
def render(self, folder_url, comp_id):
    """
        Render all renderqueueitem to 'folder_url'
    Args:
        folder_url(string): local folder path for collecting
    Returns: None
    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.render',
                                     folder_url=folder_url,
                                     comp_id=comp_id))
    return self._handle_return(res)

replace_item(item_id, path, item_name)

Replace FootageItem with new file

Parameters:

Name Type Description Default
item_id int
required
path string

absolute path

required
item_name string

label on item in Project list

required
Source code in client/ayon_aftereffects/api/ws_stub.py
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
def replace_item(self, item_id, path, item_name):
    """ Replace FootageItem with new file

        Args:
            item_id (int):
            path (string):absolute path
            item_name (string): label on item in Project list

    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.replace_item',
                                     item_id=item_id,
                                     path=path, item_name=item_name))

    return self._handle_return(res)

save()

Saves active document

Returns: None

Source code in client/ayon_aftereffects/api/ws_stub.py
442
443
444
445
446
447
448
449
450
def save(self):
    """
        Saves active document
    Returns: None
    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.save'))

    return self._handle_return(res)

saveAs(project_path, as_copy)

Saves active project to aep (copy) or png or jpg

Args: project_path(string): full local path as_copy: Returns: None

Source code in client/ayon_aftereffects/api/ws_stub.py
452
453
454
455
456
457
458
459
460
461
462
463
464
465
def saveAs(self, project_path, as_copy):
    """
        Saves active project to aep (copy) or png or jpg
    Args:
        project_path(string): full local path
        as_copy: <boolean>
    Returns: None
    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.saveAs',
                                     image_path=project_path,
                                     as_copy=as_copy))

    return self._handle_return(res)

select_items(items)

Select items in Project list

Args: items (list): of int item ids

Source code in client/ayon_aftereffects/api/ws_stub.py
229
230
231
232
233
234
235
236
def select_items(self, items):
    """
        Select items in Project list
    Args:
        items (list): of int item ids
    """
    self.websocketserver.call(
        self.client.call('AfterEffects.select_items', items=items))

set_comp_properties(comp_id, start, duration, frame_rate, width, height)

Set work area to predefined values (from Ftrack).
Work area directs what gets rendered.
Beware of rounding, AE expects seconds, not frames directly.

Parameters:

Name Type Description Default
comp_id int
required
start int

workAreaStart in frames

required
duration int

in frames

required
frame_rate float

frames in seconds

required
width int

resolution width

required
height int

resolution height

required
Source code in client/ayon_aftereffects/api/ws_stub.py
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
def set_comp_properties(self, comp_id, start, duration, frame_rate,
                        width, height):
    """
        Set work area to predefined values (from Ftrack).
        Work area directs what gets rendered.
        Beware of rounding, AE expects seconds, not frames directly.

    Args:
        comp_id (int):
        start (int): workAreaStart in frames
        duration (int): in frames
        frame_rate (float): frames in seconds
        width (int): resolution width
        height (int): resolution height
    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.set_comp_properties',
                                     item_id=comp_id,
                                     start=start,
                                     duration=duration,
                                     frame_rate=frame_rate,
                                     width=width,
                                     height=height))
    return self._handle_return(res)

set_label_color(item_id, color_idx)

Used for highlight additional information in Project panel.
Green color is loaded asset, blue is created asset

Args: item_id (int): color_idx (int): 0-16 Label colors from AE Project view

Source code in client/ayon_aftereffects/api/ws_stub.py
381
382
383
384
385
386
387
388
389
390
391
392
393
394
def set_label_color(self, item_id, color_idx):
    """
        Used for highlight additional information in Project panel.
        Green color is loaded asset, blue is created asset
    Args:
        item_id (int):
        color_idx (int): 0-16 Label colors from AE Project view
    """
    res = self.websocketserver.call(self.client.call
                                    ('AfterEffects.set_label_color',
                                     item_id=item_id,
                                     color_idx=color_idx))

    return self._handle_return(res)

get_stub()

Convenience function to get server RPC stub to call methods directed
for host (Photoshop).
It expects already created connection, started from client.
Currently, created when panel is opened (PS: Window>Extensions>AYON)

:return: where functions could be called from

Source code in client/ayon_aftereffects/api/ws_stub.py
720
721
722
723
724
725
726
727
728
729
730
731
732
def get_stub():
    """
        Convenience function to get server RPC stub to call methods directed
        for host (Photoshop).
        It expects already created connection, started from client.
        Currently, created when panel is opened (PS: Window>Extensions>AYON)
    :return: <PhotoshopClientStub> where functions could be called from
    """
    ae_stub = AfterEffectsServerStub()
    if not ae_stub.client:
        raise ConnectionNotEstablishedYet("Connection is not created yet")

    return ae_stub