@forge-sdk/media

import * as api from '@forge-sdk/media';

export const ForgeMediaErrorCode /* type inferred in source */;

export type ForgeMediaErrorCodeType = (typeof ForgeMediaErrorCode)[keyof typeof ForgeMediaErrorCode];

export class ForgeMediaError extends Error {
  public readonly code: ForgeMediaErrorCodeType;
  static generationFailed(model: string, reason: string): ForgeMediaError;
  static transcriptionFailed(model: string, reason: string): ForgeMediaError;
  static speechFailed(model: string, reason: string): ForgeMediaError;
  static videoFailed(model: string, reason: string): ForgeMediaError;
  static unsupportedFormat(format: string, supported: string[]): ForgeMediaError;
  static core(reason: string): ForgeMediaError;
}

export const ImageFormat /* type inferred in source */;

export type ImageFormat = (typeof ImageFormat)[keyof typeof ImageFormat];

export function imageMimeType(format: ImageFormat): string;

export function imageExtension(format: ImageFormat): string;

export interface ImageOptions {
  /** Image width in pixels. */
  readonly width?: number;
  /** Image height in pixels. */
  readonly height?: number;
  /** Output format. Defaults to PNG. */
  readonly format?: ImageFormat;
  /** Quality level (0-100). Only applies to JPEG and WebP. */
  readonly quality?: number;
  /** Style hint for the generator (e.g., 'vivid', 'natural'). */
  readonly style?: string;
}

export interface ImageResult {
  /** The raw image data as a Uint8Array. */
  readonly data: Uint8Array;
  /** The MIME type of the generated image. */
  readonly mimeType: string;
  /** The width of the generated image in pixels. */
  readonly width: number;
  /** The height of the generated image in pixels. */
  readonly height: number;
  /** The model identifier that produced this image. */
  readonly model: string;
}

export interface ImageProvider {
  /** Returns the model identifier. */
  modelId(): string;
  /** Returns the provider name (e.g., 'openai', 'stability'). */
  providerName(): string;

  /**
   * Generates an image from a text prompt.
   *
   * @param prompt - The text description of the desired image.
   * @param options - Optional generation parameters.
   * @returns The generated image result.
   * @throws {ForgeMediaError} If generation fails.
   */
  generateImage(prompt: string, options?: ImageOptions): Promise<ImageResult>;
}

export async function generateImage(
  provider: ImageProvider,
  prompt: string,
  options?: ImageOptions
): Promise<ImageResult>;

export { ForgeMediaError, ForgeMediaErrorCode, type ForgeMediaErrorCodeType } from './error.js';

export {
  type ImageProvider,
  type ImageOptions,
  type ImageResult,
  ImageFormat,
  imageMimeType,
  imageExtension,
  generateImage,
} from './image.js';

export {
  type SpeechProvider,
  type SpeechOptions,
  type SpeechResult,
  AudioFormat,
  audioMimeType,
  speak,
} from './speech.js';

export {
  type TranscriptionProvider,
  type TranscriptionOptions,
  type TranscriptionResult,
  type TranscriptionSegment,
  transcribe,
} from './transcription.js';

export {
  type VideoProvider,
  type VideoOptions,
  type VideoResult,
  VideoFormat,
  videoMimeType,
  generateVideo,
} from './video.js';

export const AudioFormat /* type inferred in source */;

export type AudioFormat = (typeof AudioFormat)[keyof typeof AudioFormat];

export function audioMimeType(format: AudioFormat): string;

export interface SpeechOptions {
  /** Voice identifier (provider-specific). */
  readonly voice?: string;
  /** Speech speed multiplier. 1.0 is normal speed. */
  readonly speed?: number;
  /** Output audio format. Defaults to MP3. */
  readonly format?: AudioFormat;
}

export interface SpeechResult {
  /** The raw audio data as a Uint8Array. */
  readonly audio: Uint8Array;
  /** The MIME type of the generated audio. */
  readonly mimeType: string;
  /** Duration of the audio in seconds, if known. */
  readonly durationSeconds?: number;
}

export interface SpeechProvider {
  /** Returns the model identifier. */
  modelId(): string;
  /** Returns the provider name. */
  providerName(): string;

  /**
   * Synthesizes speech from text.
   *
   * @param text - The text to convert to speech.
   * @param options - Optional synthesis parameters.
   * @returns The generated speech result.
   * @throws {ForgeMediaError} If synthesis fails.
   */
  speak(text: string, options?: SpeechOptions): Promise<SpeechResult>;
}

export async function speak(
  provider: SpeechProvider,
  text: string,
  options?: SpeechOptions
): Promise<SpeechResult>;

export interface TranscriptionSegment {
  /** Start time of the segment in seconds. */
  readonly start: number;
  /** End time of the segment in seconds. */
  readonly end: number;
  /** The transcribed text for this segment. */
  readonly text: string;
}

export interface TranscriptionOptions {
  /** Language hint (ISO 639-1 code, e.g., 'en', 'fr', 'de'). */
  readonly language?: string;
  /** Prompt hint to guide the transcription model. */
  readonly prompt?: string;
}

export interface TranscriptionResult {
  /** The full transcribed text. */
  readonly text: string;
  /** The detected or specified language. */
  readonly language?: string;
  /** Duration of the audio in seconds, if known. */
  readonly durationSeconds?: number;
  /** Word-level or sentence-level timing segments. */
  readonly segments: readonly TranscriptionSegment[];
}

export interface TranscriptionProvider {
  /** Returns the model identifier. */
  modelId(): string;
  /** Returns the provider name. */
  providerName(): string;

  /**
   * Transcribes audio to text.
   *
   * @param audio - The raw audio data.
   * @param options - Optional transcription parameters.
   * @returns The transcription result.
   * @throws {ForgeMediaError} If transcription fails.
   */
  transcribe(audio: Uint8Array, options?: TranscriptionOptions): Promise<TranscriptionResult>;
}

export async function transcribe(
  provider: TranscriptionProvider,
  audio: Uint8Array,
  options?: TranscriptionOptions
): Promise<TranscriptionResult>;

export const VideoFormat /* type inferred in source */;

export type VideoFormat = (typeof VideoFormat)[keyof typeof VideoFormat];

export function videoMimeType(format: VideoFormat): string;

export interface VideoOptions {
  /** Video width in pixels. */
  readonly width?: number;
  /** Video height in pixels. */
  readonly height?: number;
  /** Duration of the video in seconds. */
  readonly durationSeconds?: number;
  /** Output format. Defaults to MP4. */
  readonly format?: VideoFormat;
}

export interface VideoResult {
  /** The raw video data as a Uint8Array. */
  readonly data: Uint8Array;
  /** The MIME type of the generated video. */
  readonly mimeType: string;
  /** Duration of the generated video in seconds. */
  readonly durationSeconds: number;
  /** The width of the generated video in pixels. */
  readonly width: number;
  /** The height of the generated video in pixels. */
  readonly height: number;
}

export interface VideoProvider {
  /** Returns the model identifier. */
  modelId(): string;
  /** Returns the provider name. */
  providerName(): string;

  /**
   * Generates a video from a text prompt.
   *
   * @param prompt - The text description of the desired video.
   * @param options - Optional generation parameters.
   * @returns The generated video result.
   * @throws {ForgeMediaError} If generation fails.
   */
  generateVideo(prompt: string, options?: VideoOptions): Promise<VideoResult>;
}

export async function generateVideo(
  provider: VideoProvider,
  prompt: string,
  options?: VideoOptions
): Promise<VideoResult>;