flame_export

def create_otio_reference(
        clip_data: dict,
        media_info: MediaInfoFile | None = None,
        fps: float | None = None
) -> (
    otio.schema.ExternalReference |
    otio.schema.ImageSequenceReference |
    otio.schema.MissingReference
):
    """Create an OTIO reference from Flame clip data.

    Args:
        clip_data (dict): Flame clip data.
        media_info (Optional[MediaInfoFile]): Media information.
        fps (Optional[float]): Frames per second.

    Returns:
        otio.schema.ExternalReference |
        otio.schema.ImageSequenceReference |
        otio.schema.MissingReference: OTIO reference.
    """
    if not media_info:
        log.error("Media info is missing")
        return otio.schema.MissingReference(
            name=clip_data["segment_name"]
        )

    metadata = _get_metadata(clip_data)

    # Add image-based metadata if not a pure audio media
    # TODO: what happens if media is image-based but not width
    # can be reached ?
    # (could use ayon_core.lib.transcoding.get_otio_info_for_input)
    if hasattr(media_info, "width"):
        metadata.update(
            {
                "ayon.source.width": media_info.width,
                "ayon.source.height": media_info.height,
                "ayon.source.pixelAspect": media_info.pixel_aspect,
            }
        )

    duration = int(clip_data["source_duration"])

    # get file info for path and start frame
    media_start = media_info.start_frame or 0
    fps = fps or media_info.fps or OtioExportCTX.get_fps()

    path = clip_data["fpath"]

    file_name = os.path.basename(path)
    file_head, extension = os.path.splitext(file_name)

    # get padding and other file infos
    log.debug(f"_ path: {path}")

    otio_ex_ref_item = None

    sequence_match = re.match(
        # match range pattern e.g. "foo_[1001-1010].ext"
        r".*\[(?P<start_frame>\d*)-(?P<end_frame>\d*)\].?",
        media_info.file_pattern
    )

    if sequence_match:
        frame_number = sequence_match.group("start_frame")
        file_head = file_name.split(frame_number)[0]
        start_frame = int(frame_number)
        padding = len(frame_number)

        metadata.update({
            "isSequence": True,
            "padding": padding
        })

        # if it is file sequence try to create `ImageSequenceReference`
        # the OTIO might not be compatible so return nothing and do it old way
        try:
            dirname = os.path.dirname(path)
            otio_ex_ref_item = otio.schema.ImageSequenceReference(
                target_url_base=dirname + os.sep,
                name_prefix=file_head,
                name_suffix=extension,
                start_frame=start_frame,
                frame_zero_padding=padding,
                rate=fps,
                available_range=create_otio_time_range(
                    media_start,
                    duration,
                    fps
                )
            )

        # in case old OTIO create sequence as `ExternalReference`
        except AttributeError:
            dirname, file_name = os.path.split(path)
            file_name = utils.get_reformatted_filename(file_name, padded=False)
            reformated_path = os.path.join(dirname, file_name)
            otio_ex_ref_item = otio.schema.ExternalReference(
                target_url=reformated_path,
                available_range=create_otio_time_range(
                    media_start,
                    duration,
                    fps
                )
            )

    # video/audio file create `ExternalReference`
    else:
        otio_ex_ref_item = otio.schema.ExternalReference(
            target_url=path,
            available_range=create_otio_time_range(
                media_start,
                duration,
                fps
            )
        )

    # add metadata to otio item
    add_otio_metadata(otio_ex_ref_item, clip_data, **metadata)

    return otio_ex_ref_item