1
/**
2
 * Media binding for transforming media streams.
3
 * Provides the entry point for media transformation operations.
4
 */
5
interface MediaBinding {
6
	/**
7
	 * Creates a media transformer from an input stream.
8
	 * @param media - The input media bytes
9
	 * @returns A MediaTransformer instance for applying transformations
10
	 */
11
	input(media: ReadableStream<Uint8Array>): MediaTransformer
12
}
13
 
14
/**
15
 * Media transformer for applying transformation operations to media content.
16
 * Handles sizing, fitting, and other input transformation parameters.
17
 */
18
interface MediaTransformer {
19
	/**
20
	 * Applies transformation options to the media content.
21
	 * @param transform - Configuration for how the media should be transformed
22
	 * @returns A generator for producing the transformed media output
23
	 */
24
	transform(
25
		transform?: MediaTransformationInputOptions
26
	): MediaTransformationGenerator
27
 
28
	/**
29
	 * Generates the final media output with specified options.
30
	 * @param output - Configuration for the output format and parameters
31
	 * @returns The final transformation result containing the transformed media
32
	 */
33
	output(
34
		output?: MediaTransformationOutputOptions
35
	): MediaTransformationResult
36
}
37
 
38
/**
39
 * Generator for producing media transformation results.
40
 * Configures the output format and parameters for the transformed media.
41
 */
42
interface MediaTransformationGenerator {
43
	/**
44
	 * Generates the final media output with specified options.
45
	 * @param output - Configuration for the output format and parameters
46
	 * @returns The final transformation result containing the transformed media
47
	 */
48
	output(
49
		output?: MediaTransformationOutputOptions
50
	): MediaTransformationResult
51
}
52
 
53
/**
54
 * Result of a media transformation operation.
55
 * Provides multiple ways to access the transformed media content.
56
 */
57
interface MediaTransformationResult {
58
	/**
59
	 * Returns the transformed media as a readable stream of bytes.
60
	 * @returns A promise containing a readable stream with the transformed media
61
	 */
62
	media(): Promise<ReadableStream<Uint8Array>>
63
	/**
64
	 * Returns the transformed media as an HTTP response object.
65
	 * @returns The transformed media as a Promise<Response>, ready to store in cache or return to users
66
	 */
67
	response(): Promise<Response>
68
	/**
69
	 * Returns the MIME type of the transformed media.
70
	 * @returns A promise containing the content type string (e.g., 'image/jpeg', 'video/mp4')
71
	 */
72
	contentType(): Promise<string>
73
}
74
 
75
/**
76
 * Configuration options for transforming media input.
77
 * Controls how the media should be resized and fitted.
78
 */
79
type MediaTransformationInputOptions = {
80
	/** How the media should be resized to fit the specified dimensions */
81
	fit?: 'contain' | 'cover' | 'scale-down'
82
	/** Target width in pixels */
83
	width?: number
84
	/** Target height in pixels */
85
	height?: number
86
}
87
 
88
/**
89
 * Configuration options for Media Transformations output.
90
 * Controls the format, timing, and type of the generated output.
91
 */
92
type MediaTransformationOutputOptions = {
93
	/**
94
	 * Output mode determining the type of media to generate
95
	 */
96
	mode?: 'video' | 'spritesheet' | 'frame' | 'audio'
97
	/** Whether to include audio in the output */
98
	audio?: boolean
99
	/**
100
	 * Starting timestamp for frame extraction or start time for clips. (e.g. '2s').
101
	 */
102
	time?: string
103
	/**
104
	 * Duration for video clips, audio extraction, and spritesheet generation (e.g. '5s').
105
	 */
106
	duration?: string
107
	/**
108
	 * Number of frames in the spritesheet.
109
	 */
110
	imageCount?: number
111
	/**
112
	 * Output format for the generated media.
113
	 */
114
	format?: 'jpg' | 'png' | 'm4a'
115
}
116
 
117
/**
118
 * Error object for media transformation operations.
119
 * Extends the standard Error interface with additional media-specific information.
120
 */
121
interface MediaError extends Error {
122
  readonly code: number;
123
  readonly message: string;
124
  readonly stack?: string;
125
}
126