--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/media_processor/media_processor.h	Sun Jan 25 10:44:04 2026 -0800
@@ -0,0 +1,90 @@
+#ifndef MEDIA_PROCESSOR_H
+#define MEDIA_PROCESSOR_H
+
+#include <stdbool.h>
+#include <stddef.h>
+
+// Media types
+typedef enum {
+    MEDIA_TYPE_UNKNOWN = 0,
+    MEDIA_TYPE_IMAGE,
+    MEDIA_TYPE_VIDEO,
+    MEDIA_TYPE_AUDIO,
+} MediaType;
+
+// Processing status
+typedef enum {
+    MEDIA_STATUS_PENDING = 0,
+    MEDIA_STATUS_PROCESSING,
+    MEDIA_STATUS_COMPLETED,
+    MEDIA_STATUS_FAILED,
+} MediaStatus;
+
+// Result of a processing operation
+typedef struct {
+    MediaStatus status;
+    char* error_message;
+
+    // For images
+    char* original_path;    // Path to original file
+    char* webp_path;        // Path to WebP version
+
+    // For videos
+    char* hls_playlist;     // Path to .m3u8 file
+    char* thumbnail_path;   // Path to thumbnail
+    double duration;        // Duration in seconds
+} MediaResult;
+
+// Processing options
+typedef struct {
+    // Output directory (required)
+    const char* output_dir;
+
+    // Image options
+    int image_quality;      // 0-100, default 80
+    int image_max_width;    // 0 = no limit
+    int image_max_height;   // 0 = no limit
+
+    // Video options
+    int video_segment_duration; // HLS segment duration, default 6
+    int video_bitrate;          // kbps, 0 = auto
+    int video_max_width;        // 0 = no limit
+    int video_max_height;       // 0 = no limit
+    bool generate_thumbnail;    // default true
+} MediaProcessorOpts;
+
+// Initialize processor options with defaults
+MediaProcessorOpts media_processor_opts_default(const char* output_dir);
+
+// Detect media type from file extension
+MediaType media_detect_type(const char* filename);
+
+// Get MIME type string
+const char* media_type_to_mime(MediaType type);
+
+// Process a single file (auto-detects type)
+// Returns a MediaResult that must be freed with media_result_free()
+MediaResult* media_process_file(const char* input_path, const char* id, MediaProcessorOpts* opts);
+
+// Process image specifically
+MediaResult* media_process_image(const char* input_path, const char* id, MediaProcessorOpts* opts);
+
+// Process video specifically
+MediaResult* media_process_video(const char* input_path, const char* id, MediaProcessorOpts* opts);
+
+// Free a MediaResult
+void media_result_free(MediaResult* result);
+
+// Generate a unique ID for a media file
+char* media_generate_id(void);
+
+// Utility: Copy file to destination
+bool media_copy_file(const char* src, const char* dst);
+
+// Utility: Get file extension (returns pointer into filename, do not free)
+const char* media_get_extension(const char* filename);
+
+// Utility: Check if path is safe (no directory traversal)
+bool media_path_is_safe(const char* path);
+
+#endif // MEDIA_PROCESSOR_H