import { ContentType } from "./contentType";
import { MixerRole } from "./mixerRole";
import { Audio } from "./timeline/audio";
import { Clip } from "./timeline/clip";
import { Clips } from "./timeline/clips";
import { Timeline } from "./timeline/timeline";
import { Warp } from "./timeline/warp";
import { Track } from "./track";
export declare class Utility {
    /**
     * Adds an attribute from a target object to an XML attributes object, handling optionality and value adaptation.
     * If the attribute is required and the value (after potential adaptation) is undefined, it throws an error.
     * If the attribute is optional and the value is undefined, it does nothing.
     * @param attributes The object to add the attribute to (e.g., for XML serialization).
     * @param attributeName The name of the attribute (without '@_').
     * @param targetObject The object containing the attribute value.
     * @param options Configuration options.
     * @param options.required If true, throws an error if the final attributeValue is undefined. Defaults to false.
     * @param options.adapter An optional function to convert the attributeValue before adding it (e.g., DoubleAdapter.toXml).
     *                        The adapter should return the processed value or undefined if it shouldn't be added.
     * @param options.sourceProperty The name of the property on the targetObject to get the value from. Defaults to attributeName.
     *
     * @example
     * // Add a required attribute
     * Utility.addAttribute(attributes, "name", this, { required: true });
     *
     * @example
     * // Add an optional attribute
     * Utility.addAttribute(attributes, "color", this);
     *
     * @example
     * // Add an optional attribute using an adapter (e.g., duration with DoubleAdapter)
     * Utility.addAttribute(attributes, "duration", this, { adapter: DoubleAdapter.toXml });
     *
     * @example
     * // Add an optional enum attribute (e.g., timeUnit)
     * Utility.addAttribute(attributes, "contentTimeUnit", this);
     *
     * @example
     * // Add an optional boolean attribute (e.g., solo)
     * Utility.addAttribute(attributes, "solo", this);
     *
     * @example
     * // Add an optional attribute using a source property (e.g., destination.id)
     * Utility.addAttribute(attributes, "destination", this, { sourceProperty: "destination.id" });
     */
    static addAttribute(attributes: any, attributeName: string, targetObject: any, options?: {
        required?: boolean;
        adapter?: (value: any) => any | undefined;
        sourceProperty?: string;
    }): void;
    /**
     * Populates a target object's property from an XML attribute, handling various types,
     * validation, and optionality.
     *
     * @template T The expected type of the attribute value after processing.
     * @param xmlObject The XML object (parsed from XML) containing the attribute.
     * @param attributeName The name of the attribute in the XML (without the '@_').
     * @param targetObject The object whose property should be populated.
     * @param options Configuration options for processing the attribute.
     * @param options.required If true, throws an error if the attribute is missing. Defaults to false.
     * @param options.castTo The constructor of the type to cast the value to (e.g., Number, Boolean, MixerRole, Interpolation).
     *                       Use for primitive types (Number, Boolean) and simple string-based enums/types.
     *                       For complex types requiring specific parsing logic, use an adapter instead.
     * @param options.adapter A function to convert the raw XML attribute value to the desired type T.
     *                        Use for complex types or when specific parsing logic is needed (e.g., DoubleAdapter.fromXml).
     * @param options.validator A function to validate the processed value. Should return true if valid, false otherwise.
     * @param options.targetProperty The name of the property on the targetObject to populate. Defaults to attributeName.
     *
     * @example
     * // Required number attribute (e.g., numerator)
     * Utility.populateAttribute<number>(xmlObject, "numerator", this, { required: true, castTo: Number });
     *
     * @example
     * // Required enum attribute (e.g., role)
     * Utility.populateAttribute<MixerRole>(xmlObject, "role", this, { required: true, castTo: MixerRole });
     *
     * @example
     * // Required number attribute with specific validator (e.g., audioChannels > 0)
     * Utility.populateAttribute<number>(xmlObject, "audioChannels", this, {
     *   required: true,
     *   castTo: Number,
     *   validator: (v) => v > 0
     * });
     *
     * @example
     * // Optional boolean attribute (e.g., solo)
     * Utility.populateAttribute<boolean>(xmlObject, "solo", this, { castTo: Boolean });
     *
     * @example
     * // Required attribute using an adapter (e.g., value with DoubleAdapter)
     * Utility.populateAttribute<number>(xmlObject, "value", this, {
     *   required: true,
     *   adapter: DoubleAdapter.fromXml
     * });
     *
     * @example
     * // Optional enum attribute (e.g., interpolation)
     * Utility.populateAttribute<Interpolation>(xmlObject, "interpolation", this, { castTo: Interpolation });
     *
     * @example
     * // Optional string attribute (e.g., algorithm) - no castTo/adapter needed
     * Utility.populateAttribute<string>(xmlObject, "algorithm", this);
     */
    static populateAttribute<T>(xmlObject: any, attributeName: string, targetObject: any, options?: {
        required?: boolean;
        castTo?: any;
        adapter?: (value: any) => T | undefined;
        validator?: (value: T) => boolean;
        targetProperty?: string;
    }): void;
    /**
     * Groups an array of objects by their root XML tag name after calling toXmlObject on each.
     * This is useful for creating nested XML structures where elements of different types
     * need to be grouped under their respective tag names.
     * @param children The array of objects to group. Each object is expected to have a toXmlObject method.
     * @returns An object where keys are XML tag names and values are arrays of the corresponding XML content,
     *          or undefined if the input array is null, undefined, or empty.
     */
    static groupChildrenByTagName(children: any[]): any | undefined;
    /**
     * Creates a new Track instance with a configured Channel.
     * @param name The name of the track.
     * @param contentTypes The set of content types the track can hold.
     * @param mixerRole The role of the track in the mixer.
     * @param volume The initial volume level (linear).
     * @param pan The initial pan position (normalized).
     * @returns A new Track instance.
     */
    static createTrack(name: string, contentTypes: Set<ContentType>, mixerRole: MixerRole, volume: number, pan: number): Track;
    /**
     * Creates a new Audio timeline instance.
     * @param relativePath The path to the audio file, relative to the project.
     * @param sampleRate The sample rate of the audio file.
     * @param channels The number of channels in the audio file.
     * @param duration The duration of the audio file in seconds.
     * @returns A new Audio instance.
     */
    static createAudio(relativePath: string, sampleRate: number, channels: number, duration: number): Audio;
    /**
     * Creates a new Warp point instance.
     * @param time The timeline time (in beats or seconds depending on context).
     * @param contentTime The corresponding time within the audio content (in seconds).
     * @returns A new Warp instance.
     */
    static createWarp(time: number, contentTime: number): Warp;
    /**
     * Creates a new Clip instance.
     * @param content The timeline content of the clip (e.g., Audio, Notes).
     * @param time The start time of the clip on the parent timeline.
     * @param duration The duration of the clip on the parent timeline.
     * @returns A new Clip instance.
     */
    static createClip(content: Timeline, time: number, duration: number): Clip;
    /**
     * Creates a new Clips timeline instance containing the provided clips.
     * @param clips The Clip instances to include in the timeline.
     * @returns A new Clips instance.
     */
    static createClips(...clips: Clip[]): Clips;
    /**
     * Populates an array property of a target object by iterating through the
     * child elements of an XML object and using a provided registry to create
     * instances based on the XML tag names.
     *
     * @template T The expected type of the instances created by the registry.
     * @param xmlObject The XML object (parsed from XML) containing the child elements.
     * @param targetProperty The name of the property on the target object to populate.
     * @param targetObject The object whose property should be populated.
     * @param registry The registry to use for creating instances (e.g., TimelineRegistry, DeviceRegistry).
     * @param options Configuration options.
     * @param options.skipTags An optional array of tag names to skip during iteration (e.g., "@_", "Target").
     * @param options.onInstanceCreated An optional callback function to process each created instance before adding it to the array.
     *                                  If this function returns false, the instance is not added.
     * @param options.onError An optional callback function to handle errors during instance creation.
     *
     * @example
     * // Populate an array of Timeline instances
     * Utility.populateChildrenFromXml<Timeline>(xmlObject, "lanes", this, {
     *   createFromXml: (tagName: string, xmlData: any) =>
     *     TimelineRegistry.createTimelineFromXml(tagName, xmlData),
     *   onInstanceCreated: (instance: Timeline, tagName: string) => {
     *     if (!(instance instanceof Timeline)) {
     *       console.warn(
     *         `TimelineRegistry returned non-Timeline instance for tag ${tagName}`
     *       );
     *       return false; // Do not add to lanes array
     *     }
     *     return true; // Add to lanes array
     *   },
     *   onError: (error: unknown, tagName: string) => {
     *     console.error(
     *       `Error deserializing nested timeline element ${tagName} in Lanes:`,
     *       error
     *     );
     *   },
     * });
     */
    static populateChildrenFromXml<T>(xmlObject: any, targetProperty: string, targetObject: any, registry: {
        createFromXml: (tagName: string, xmlData: any) => T | undefined;
    }, options?: {
        skipTags?: string[];
        onInstanceCreated?: (instance: T, tagName: string, xmlData: any) => boolean | void;
        onError?: (error: unknown, tagName: string, xmlData: any) => void;
    }): void;
    /**
     * Populates a single property of a target object by iterating through the
     * child elements of an XML object and using a provided registry to create
     * a single instance based on the XML tag names. It expects only one matching
     * child element.
     *
     * @template T The expected type of the instance created by the registry.
     * @param xmlObject The XML object (parsed from XML) containing the child element.
     * @param targetProperty The name of the property on the target object to populate.
     * @param targetObject The object whose property should be populated.
     * @param registry The registry to use for creating the instance (e.g., TimelineRegistry, DeviceRegistry).
     * @param options Configuration options.
     * @param options.skipTags An optional array of tag names to skip during iteration (e.g., "@_").
     * @param options.onError An optional callback function to handle errors during instance creation.
     * @returns The created instance, or undefined if no matching element was found or an error occurred.
     *
     * @example
     * // Populate a single Timeline instance for clip content
     * Utility.populateChildFromXml<Timeline>(xmlObject, "content", this, {
     *   createFromXml: (tagName: string, xmlData: any) =>
     *     TimelineRegistry.createTimelineFromXml(tagName, xmlData),
     * }, {
     *   onError: (error: unknown, tagName: string) => {
     *     console.error(
     *       `Error deserializing nested timeline content ${tagName} in Clip:`,
     *       error
     *     );
     *   },
     * });
     */
    static populateChildFromXml<T>(xmlObject: any, targetProperty: string, targetObject: any, registry: {
        createFromXml: (tagName: string, xmlData: any) => T | undefined;
    }, options?: {
        skipTags?: string[];
        onError?: (error: unknown, tagName: string, xmlData: any) => void;
    }): T | undefined;
}