lipdub 0.1.0

data/lib/lipdub/resources/shots.rb

@@ -0,0 +1,400 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Lipdub
+  module Resources
+    class Shots < Base
+      # List all available shots
+      #
+      # @param page [Integer] Page number for pagination (defaults to 1)
+      # @param per_page [Integer] Number of items per page, max 100 (defaults to 20)
+      # @return [Hash] Response containing list of shots and count
+      #
+      # @example
+      #   shots = client.shots.list(page: 1, per_page: 50)
+      #   # => {
+      #   #   "data" => [
+      #   #     {
+      #   #       "shot_id" => 99,
+      #   #       "shot_label" => "api-full-test-new.mp4",
+      #   #       "shot_project_id" => 37,
+      #   #       "shot_scene_id" => 37,
+      #   #       "shot_project_name" => "Lee Studios",
+      #   #       "shot_scene_name" => "Under the tent"
+      #   #     }
+      #   #   ],
+      #   #   "count" => 1
+      #   # }
+      def list(page: 1, per_page: 20)
+        validate_pagination_params!(page, per_page)
+        
+        params = {
+          page: page,
+          per_page: per_page
+        }
+        get("/v1/shots", params)
+      end
+
+      # Get shot processing status
+      #
+      # @param shot_id [String, Integer] Unique identifier of the shot
+      # @return [Hash] Response containing shot status and processing information
+      #
+      # @example
+      #   status = client.shots.status(123)
+      def status(shot_id)
+        get("/v1/shots/#{shot_id}/status")
+      end
+
+      # Generate lip-dubbed video
+      #
+      # @param shot_id [String, Integer] Unique identifier of the shot
+      # @param audio_id [String] Unique identifier of the audio file
+      # @param output_filename [String] Name for the output file
+      # @param language [String, nil] Optional language specification (ISO 639-1)
+      # @param start_frame [Integer, nil] Frame number to start the lip-sync from (defaults to 0)
+      # @param loop_video [Boolean, nil] Whether to loop the video during rendering (defaults to false)
+      # @param full_resolution [Boolean, nil] Whether to use full resolution (defaults to true)
+      # @param callback_url [String, nil] Optional HTTPS URL for completion callback
+      # @param timecode_ranges [Array, nil] Optional list of timecode ranges to render
+      # @return [Hash] Response containing generation details and generate_id
+      #
+      # @example
+      #   response = client.shots.generate(
+      #     shot_id: 123,
+      #     audio_id: "audio_456",
+      #     output_filename: "dubbed_video.mp4",
+      #     language: "en-US",
+      #     start_frame: 0,
+      #     loop_video: false,
+      #     full_resolution: true,
+      #     callback_url: "https://example.com/webhook"
+      #   )
+      #   # => {
+      #   #   "generate_id" => 456
+      #   # }
+      def generate(shot_id:, audio_id:, output_filename:, language: nil, start_frame: nil, 
+                   loop_video: nil, full_resolution: nil, callback_url: nil, timecode_ranges: nil)
+        body = {
+          audio_id: audio_id,
+          output_filename: output_filename
+        }
+        
+        body[:language] = language if language
+        body[:start_frame] = start_frame if start_frame
+        body[:loop_video] = loop_video unless loop_video.nil?
+        body[:full_resolution] = full_resolution unless full_resolution.nil?
+        body[:callback_url] = callback_url if callback_url
+        body[:timecode_ranges] = timecode_ranges if timecode_ranges
+
+        post("/v1/shots/#{shot_id}/generate", body)
+      end
+
+      # Get generation status
+      #
+      # @param shot_id [String, Integer] Unique identifier of the shot
+      # @param generate_id [String] Unique identifier of the generation request
+      # @return [Hash] Response containing generation progress and status
+      #
+      # @example
+      #   status = client.shots.generation_status(123, "gen_789")
+      def generation_status(shot_id, generate_id)
+        get("/v1/shots/#{shot_id}/generate/#{generate_id}")
+      end
+
+      # Download generated video
+      #
+      # @param shot_id [String, Integer] Unique identifier of the shot
+      # @param generate_id [String] Unique identifier of the generation request
+      # @return [Hash] Response containing download_url for the dubbed video
+      #
+      # @example
+      #   download_info = client.shots.download(123, "gen_789")
+      #   # => {
+      #   #   "data" => {
+      #   #     "download_url" => "https://storage.lipdub.ai/download/gen_789?token=xyz"
+      #   #   }
+      #   # }
+      def download(shot_id, generate_id)
+        get("/v1/shots/#{shot_id}/generate/#{generate_id}/download")
+      end
+
+      # Download generated video file directly to a local path
+      #
+      # @param shot_id [String, Integer] Unique identifier of the shot
+      # @param generate_id [String] Unique identifier of the generation request
+      # @param file_path [String] Local path where the video should be saved
+      # @return [String] Path to the downloaded file
+      #
+      # @example
+      #   local_path = client.shots.download_file(123, "gen_789", "output/dubbed_video.mp4")
+      #   # Downloads the file and returns "output/dubbed_video.mp4"
+      def download_file(shot_id, generate_id, file_path)
+        download_response = download(shot_id, generate_id)
+        download_url = download_response.dig("data", "download_url") if download_response.is_a?(Hash)
+        
+        # Handle case where response might still be a string (fallback)
+        if download_response.is_a?(String)
+          parsed = JSON.parse(download_response)
+          download_url = parsed.dig("data", "download_url")
+        end
+        
+        raise APIError, "Download URL not found in response" unless download_url
+
+        download_file_from_url(download_url, file_path)
+      end
+
+      # Complete generation workflow: generate and wait for completion
+      #
+      # @param shot_id [String, Integer] Unique identifier of the shot
+      # @param audio_id [String] Unique identifier of the audio file
+      # @param output_filename [String] Name for the output file
+      # @param language [String, nil] Optional language specification (ISO 639-1)
+      # @param start_frame [Integer, nil] Frame number to start the lip-sync from (defaults to 0)
+      # @param loop_video [Boolean, nil] Whether to loop the video during rendering (defaults to false)
+      # @param full_resolution [Boolean, nil] Whether to use full resolution (defaults to true)
+      # @param callback_url [String, nil] Optional HTTPS URL for completion callback
+      # @param timecode_ranges [Array, nil] Optional list of timecode ranges to render
+      # @param polling_interval [Integer] Seconds to wait between status checks (default: 10)
+      # @param max_wait_time [Integer] Maximum seconds to wait for completion (default: 1800)
+      # @return [Hash] Response containing final generation status
+      #
+      # @example
+      #   result = client.shots.generate_and_wait(
+      #     shot_id: 123,
+      #     audio_id: "audio_456",
+      #     output_filename: "dubbed_video.mp4",
+      #     polling_interval: 15,
+      #     max_wait_time: 3600
+      #   )
+      def generate_and_wait(shot_id:, audio_id:, output_filename:, language: nil, 
+                           start_frame: nil, loop_video: nil, full_resolution: nil, 
+                           callback_url: nil, timecode_ranges: nil, polling_interval: 10, max_wait_time: 1800)
+        # Start generation
+        generate_response = generate(
+          shot_id: shot_id,
+          audio_id: audio_id,
+          output_filename: output_filename,
+          language: language,
+          start_frame: start_frame,
+          loop_video: loop_video,
+          full_resolution: full_resolution,
+          callback_url: callback_url,
+          timecode_ranges: timecode_ranges
+        )
+
+        generate_id = nil
+        if generate_response.is_a?(Hash)
+          generate_id = generate_response["generate_id"] || generate_response.dig("data", "generate_id")
+        elsif generate_response.is_a?(String)
+          parsed = JSON.parse(generate_response)
+          generate_id = parsed["generate_id"] || parsed.dig("data", "generate_id")
+        end
+        
+        raise APIError, "Generate ID not found in response" unless generate_id
+
+        # Poll for completion
+        start_time = Time.now
+        loop do
+          status_response = generation_status(shot_id, generate_id)
+          
+          # Handle both Hash and String responses
+          status = nil
+          if status_response.is_a?(Hash)
+            status = status_response.dig("data", "status") || status_response["status"]
+          elsif status_response.is_a?(String)
+            parsed = JSON.parse(status_response)
+            status = parsed.dig("data", "status") || parsed["status"]
+            status_response = parsed # Use parsed version for return
+          end
+
+          case status
+          when "completed", "success"
+            return status_response
+          when "failed", "error"
+            raise APIError, "Generation failed: #{status_response}"
+          end
+
+          # Check timeout
+          if Time.now - start_time > max_wait_time
+            raise TimeoutError, "Generation did not complete within #{max_wait_time} seconds"
+          end
+
+          sleep(polling_interval)
+        end
+      end
+
+      # Get actors for a shot
+      #
+      # @param shot_id [String, Integer] Unique identifier of the shot
+      # @return [Hash] Response containing actors information for the shot
+      #
+      # @example
+      #   actors = client.shots.actors(123)
+      def actors(shot_id)
+        get("/v1/shots/#{shot_id}/actors")
+      end
+
+      # Translate a LipDub for a shot
+      #
+      # @param shot_id [String, Integer] Unique identifier of the shot
+      # @param source_language [String] Source language code
+      # @param target_language [String] Target language code
+      # @param full_resolution [Boolean, nil] Whether to render in full resolution (defaults to true)
+      # @return [Hash] Response containing translation details
+      #
+      # @example
+      #   response = client.shots.translate(
+      #     shot_id: 123,
+      #     source_language: "English",
+      #     target_language: "Spanish",
+      #     full_resolution: true
+      #   )
+      def translate(shot_id:, source_language:, target_language:, full_resolution: nil)
+        body = {
+          source_language: source_language,
+          target_language: target_language
+        }
+        body[:full_resolution] = full_resolution unless full_resolution.nil?
+
+        post("/v1/shots/#{shot_id}/translate", body)
+      end
+
+      # Generate multi-actor LipDub for a shot
+      #
+      # @param shot_id [String, Integer] Unique identifier of the shot
+      # @param params [Hash] Multi-actor generation parameters
+      # @return [Hash] Response containing multi-actor generation details
+      #
+      # @example
+      #   response = client.shots.generate_multi_actor(
+      #     shot_id: 123,
+      #     params: { actors: [...] }
+      #   )
+      def generate_multi_actor(shot_id:, **params)
+        post("/v1/shots/#{shot_id}/generate-multi-actor", params)
+      end
+
+      # Helper method to validate timecode ranges
+
+      # Validates timecode ranges for selective lip-dubbing
+      # @param ranges [Array<Array>] Array of [start, end] timecode pairs
+      # @param video_duration [Numeric] Total video duration in seconds (optional)
+      # @return [Boolean] true if valid
+      # @raise [ArgumentError] if ranges are invalid
+      def validate_timecode_ranges(ranges, video_duration: nil)
+        return true if ranges.nil? || ranges.empty?
+
+        unless ranges.is_a?(Array)
+          raise ArgumentError, "timecode_ranges must be an array"
+        end
+
+        ranges.each_with_index do |range, index|
+          unless range.is_a?(Array) && range.length == 2
+            raise ArgumentError, "Each timecode range must be an array of [start, end] at index #{index}"
+          end
+
+          start_time, end_time = range
+          start_seconds = parse_timecode_to_seconds(start_time)
+          end_seconds = parse_timecode_to_seconds(end_time)
+
+          if start_seconds >= end_seconds
+            raise ArgumentError, "Start time must be before end time in range #{index}: #{range}"
+          end
+
+          if video_duration && end_seconds > video_duration
+            raise ArgumentError, "End time #{end_time} exceeds video duration #{video_duration} in range #{index}"
+          end
+        end
+
+        # Check for overlapping ranges
+        sorted_ranges = ranges.map { |r| [parse_timecode_to_seconds(r[0]), parse_timecode_to_seconds(r[1])] }
+                             .sort_by(&:first)
+        
+        sorted_ranges.each_cons(2) do |(prev_start, prev_end), (curr_start, curr_end)|
+          if curr_start < prev_end
+            raise ArgumentError, "Overlapping timecode ranges detected: [#{prev_start}, #{prev_end}] and [#{curr_start}, #{curr_end}]"
+          end
+        end
+
+        true
+      end
+
+      # Adds frame buffer to timecode ranges for seamless blending
+      # @param ranges [Array<Array>] Array of [start, end] timecode pairs
+      # @param buffer_frames [Integer] Number of frames to add as buffer (default: 10)
+      # @param fps [Integer] Frames per second (default: 30)
+      # @param video_duration [Numeric] Total video duration to clamp end times (optional)
+      # @return [Array<Array>] Buffered timecode ranges
+      def add_frame_buffer(ranges, buffer_frames: 10, fps: 30, video_duration: nil)
+        return ranges if ranges.nil? || ranges.empty?
+        
+        buffer_seconds = buffer_frames.to_f / fps
+        
+        ranges.map do |start_time, end_time|
+          start_seconds = parse_timecode_to_seconds(start_time, fps: fps)
+          end_seconds = parse_timecode_to_seconds(end_time, fps: fps)
+          
+          buffered_start = [start_seconds - buffer_seconds, 0.0].max
+          buffered_end = end_seconds + buffer_seconds
+          
+          if video_duration
+            buffered_end = [buffered_end, video_duration].min
+          end
+          
+          [buffered_start, buffered_end]
+        end
+      end
+
+      # Converts timecode to seconds
+      # @param timecode [String, Numeric] Either numeric seconds or SMPTE format "HH:MM:SS:FF"
+      # @param fps [Integer] Frames per second for SMPTE conversion (default: 30)
+      # @return [Float] Time in seconds
+      def parse_timecode_to_seconds(timecode, fps: 30)
+        case timecode
+        when Numeric
+          timecode.to_f
+        when String
+          if timecode.match?(/^\d{2}:\d{2}:\d{2}:\d{2}$/)
+            # SMPTE format: HH:MM:SS:FF
+            hours, minutes, seconds, frames = timecode.split(':').map(&:to_i)
+            hours * 3600 + minutes * 60 + seconds + frames.to_f / fps
+          else
+            # Try parsing as float string
+            timecode.to_f
+          end
+        else
+          raise ArgumentError, "Invalid timecode format: #{timecode}. Use numeric seconds or SMPTE format (HH:MM:SS:FF)"
+        end
+      end
+
+      private
+
+      def validate_pagination_params!(page, per_page)
+        raise ValidationError, "Page must be >= 1" if page < 1
+        raise ValidationError, "Per page must be between 1 and 100" unless (1..100).include?(per_page)
+      end
+
+      def download_file_from_url(url, file_path)
+        # Create directory if it doesn't exist
+        FileUtils.mkdir_p(File.dirname(file_path))
+
+        connection = Faraday.new do |conn|
+          conn.adapter Faraday.default_adapter
+        end
+
+        response = connection.get(url)
+        
+        if response.success?
+          File.open(file_path, 'wb') do |file|
+            file.write(response.body)
+          end
+          file_path
+        else
+          raise APIError, "Failed to download file: HTTP #{response.status}"
+        end
+      end
+    end
+  end
+end

data/lib/lipdub/resources/videos.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Lipdub
+  module Resources
+    class Videos < Base
+      # Initiate video upload process
+      #
+      # @param size_bytes [Integer] Size of the video file in bytes
+      # @param file_name [String] Name of the video file with extension
+      # @param content_type [String] MIME type of the video file
+      # @param video_source_url [String, nil] Optional URL of the video source file
+      # @return [Hash] Response containing video_id, upload_url, success_url, and failure_url
+      #
+      # @example
+      #   response = client.videos.upload(
+      #     size_bytes: 52428800,
+      #     file_name: "sample.mp4",
+      #     content_type: "video/mp4"
+      #   )
+      #   # => {
+      #   #   "data" => {
+      #   #     "video_id" => "video_123",
+      #   #     "upload_url" => "https://storage.lipdub.ai/upload/video_123?token=xyz",
+      #   #     "success_url" => "https://api.lipdub.ai/v1/video/success/video_123",
+      #   #     "failure_url" => "https://api.lipdub.ai/v1/video/failure/video_123"
+      #   #   }
+      #   # }
+      def upload(size_bytes:, file_name:, content_type:, video_source_url: nil)
+        body = {
+          size_bytes: size_bytes,
+          file_name: file_name,
+          content_type: content_type
+        }
+        body[:video_source_url] = video_source_url if video_source_url
+
+        post("/v1/video", body)
+      end
+
+      # Upload video file to the provided upload URL
+      #
+      # @param upload_url [String] The upload URL received from the upload method
+      # @param file_content [String, IO] The video file content to upload
+      # @param content_type [String] MIME type of the video file
+      # @return [Hash] Response from the upload
+      #
+      # @example
+      #   file_content = File.read("sample.mp4")
+      #   client.videos.upload_file(upload_url, file_content, "video/mp4")
+      def upload_file(upload_url, file_content, content_type)
+        put_file(upload_url, file_content, content_type)
+      end
+
+      # Complete video upload process with a file path
+      #
+      # @param file_path [String] Path to the video file
+      # @param content_type [String, nil] MIME type of the video file (auto-detected if nil)
+      # @return [Hash] Response containing shot_id and asset_type after successful upload
+      #
+      # @example
+      #   response = client.videos.upload_complete("path/to/video.mp4")
+      #   # This method handles the entire upload flow:
+      #   # 1. Initiates upload
+      #   # 2. Uploads the file
+      #   # 3. Calls success callback
+      def upload_complete(file_path, content_type: nil)
+        raise ArgumentError, "File does not exist: #{file_path}" unless File.exist?(file_path)
+
+        file_content = File.read(file_path)
+        file_name = File.basename(file_path)
+        content_type ||= detect_content_type(file_path)
+        size_bytes = File.size(file_path)
+
+        # Step 1: Initiate upload
+        upload_response = upload(
+          size_bytes: size_bytes,
+          file_name: file_name,
+          content_type: content_type
+        )
+
+        video_id = upload_response.dig("data", "video_id") if upload_response.is_a?(Hash)
+        upload_url = upload_response.dig("data", "upload_url") if upload_response.is_a?(Hash)
+        
+        # Handle case where response might still be a string (fallback)
+        if upload_response.is_a?(String)
+          parsed = JSON.parse(upload_response)
+          video_id = parsed.dig("data", "video_id")
+          upload_url = parsed.dig("data", "upload_url")
+        end
+        
+        begin
+          # Step 2: Upload file
+          upload_file(upload_url, file_content, content_type)
+          
+          # Step 3: Mark as successful
+          success(video_id)
+        rescue => e
+          # Step 3 (alternative): Mark as failed
+          failure(video_id)
+          raise e
+        end
+      end
+
+      # Mark video upload as successful
+      #
+      # @param video_id [String] Unique identifier of the video file
+      # @return [Hash] Response containing shot_id and asset_type
+      #
+      # @example
+      #   response = client.videos.success("video_123")
+      #   # => {
+      #   #   "data" => {
+      #   #     "shot_id" => 123,
+      #   #     "asset_type" => "dubbing-video"
+      #   #   }
+      #   # }
+      def success(video_id)
+        post("/v1/video/success/#{video_id}")
+      end
+
+      # Mark video upload as failed
+      #
+      # @param video_id [String] Unique identifier of the video file
+      # @return [Hash] Response (typically empty)
+      #
+      # @example
+      #   client.videos.failure("video_123")
+      def failure(video_id)
+        post("/v1/video/failure/#{video_id}")
+      end
+
+      # Get video processing status
+      #
+      # @param video_id [String] Unique identifier of the video file
+      # @return [Hash] Response containing video status information
+      #
+      # @example
+      #   status = client.videos.status("video_123")
+      def status(video_id)
+        get("/v1/video/status/#{video_id}")
+      end
+
+      private
+
+      def detect_content_type(file_path)
+        extension = File.extname(file_path).downcase
+        case extension
+        when '.mp4'
+          'video/mp4'
+        when '.mov'
+          'video/quicktime'
+        when '.avi'
+          'video/x-msvideo'
+        when '.webm'
+          'video/webm'
+        when '.mkv'
+          'video/x-matroska'
+        else
+          'video/mp4' # Default fallback
+        end
+      end
+    end
+  end
+end

data/lib/lipdub/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Lipdub
+  VERSION = "0.1.0"
+end

data/lib/lipdub.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/multipart"
+require "json"
+
+require_relative "lipdub/version"
+require_relative "lipdub/configuration"
+require_relative "lipdub/client"
+require_relative "lipdub/errors"
+require_relative "lipdub/resources/base"
+require_relative "lipdub/resources/videos"
+require_relative "lipdub/resources/audios"
+require_relative "lipdub/resources/shots"
+require_relative "lipdub/resources/projects"
+
+module Lipdub
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.client
+    @client ||= Client.new
+  end
+end

data/lipdub.gemspec

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "lib/lipdub/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "lipdub"
+  spec.version = Lipdub::VERSION
+  spec.authors = ["Upriser"]
+  spec.email = ["support@upriser.com"]
+
+  spec.summary = "Ruby client library for Lipdub.ai API"
+  spec.description = "A comprehensive Ruby client for interacting with the Lipdub.ai API, providing video and audio upload capabilities, AI-powered lip-dubbing generation, and processing status monitoring."
+  spec.homepage = "https://github.com/upriser/lipdub-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/upriser/lipdub-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/upriser/lipdub-ruby/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z 2>/dev/null`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "faraday", "~> 2.0"
+  spec.add_dependency "faraday-multipart", "~> 1.0"
+
+  # Development dependencies
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "webmock", "~> 3.0"
+  spec.add_development_dependency "vcr", "~> 6.0"
+  spec.add_development_dependency "rubocop", "~> 1.0"
+  spec.add_development_dependency "yard", "~> 0.9"
+  spec.add_development_dependency "bundler-audit", "~> 0.9"
+end