Class: RubyLLM::VideoJob

Inherits:
Object
  • Object
show all
Includes:
Support::Inspectable
Defined in:
lib/ruby_llm/video_job.rb

Overview

A VideoJob is an in-flight video generation. RubyLLM.animate_later returns one immediately; poll it with #refresh and read the finished clip with #video. RubyLLM.animate runs the same job through #wait.

job = RubyLLM.animate_later("a paper boat sailing down a gutter")
job.wait
job.video.save("boat.mp4")

Constant Summary

Constants included from Support::Inspectable

Support::Inspectable::TRUNCATE_AT

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Support::Inspectable

#full_inspect, #inspect, #pretty_print

Constructor Details

#initialize(id:, protocol:, model: nil, status: :pending, raw: nil, error: nil) ⇒ VideoJob

:nodoc:



68
69
70
71
72
73
74
75
 
# File 'lib/ruby_llm/video_job.rb', line 68

def initialize(id:, protocol:, model: nil, status: :pending, raw: nil, error: nil) # :nodoc:
  @id = id
  @protocol = protocol
  @model = model
  @status = status
  @raw = raw
  @error = error
end

Instance Attribute Details

#error ⇒ Object (readonly)

The provider's failure message when #failed?, or nil.



25
26
27
 
# File 'lib/ruby_llm/video_job.rb', line 25

def error
  @error
end

#id ⇒ Object (readonly)

The provider's id for the job.



16
17
18
 
# File 'lib/ruby_llm/video_job.rb', line 16

def id
  @id
end

#model ⇒ Object (readonly)

The id of the model rendering the video.



22
23
24
 
# File 'lib/ruby_llm/video_job.rb', line 22

def model
  @model
end

#raw ⇒ Object (readonly)

The provider's raw response from the last submit or poll.



28
29
30
 
# File 'lib/ruby_llm/video_job.rb', line 28

def raw
  @raw
end

#status ⇒ Object (readonly)

The job state: :pending, :completed, or :failed.



19
20
21
 
# File 'lib/ruby_llm/video_job.rb', line 19

def status
  @status
end

Class Method Details

.animate_later(prompt = nil, model: nil, provider: nil, assume_model_exists: false, context: nil, with: nil, extend: nil, provider_options: {}, metadata: nil) ⇒ Object

Submits a video generation job and returns a VideoJob without waiting for the result. Most code calls this through RubyLLM.animate_later. Takes the same arguments as Video.animate.

job = RubyLLM.animate_later("a hummingbird in slow motion")
job.id      # => "0eb6910f-a353-4699-9d1e-6a4f7a5b39e2"
job.done?   # => false


38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/ruby_llm/video_job.rb', line 38

def self.animate_later(prompt = nil,
                       model: nil,
                       provider: nil,
                       assume_model_exists: false,
                       context: nil,
                       with: nil,
                       extend: nil,
                       provider_options: {},
                       metadata: nil)
  config = context&.config || RubyLLM.config
  model ||= config.default_video_model
  model, provider_instance = Models.resolve(model, provider: provider, assume_model_exists: assume_model_exists,
                                                   config: config)
  payload = {
    provider: provider_instance.slug,
    provider_class: provider_instance.name,
    model: model.id,
    model_info: model,
    prompt: prompt,
    provider_options: provider_options,
    metadata: metadata
  }

  RubyLLM.instrument('video_job.ruby_llm', payload, config: config) do |event|
    job = provider_instance.animate_later(prompt, model:, with:, extend:, provider_options:)
    event[:job_id] = job.id
    job
  end
end

Instance Method Details

#completed? ⇒ Boolean

Returns true when the job finished with a video.

Returns:

  • (Boolean) 


88
89
90
 
# File 'lib/ruby_llm/video_job.rb', line 88

def completed?
  status == :completed
end

#done? ⇒ Boolean

Returns true once the job finished, successfully or not.

Returns:

  • (Boolean) 


83
84
85
 
# File 'lib/ruby_llm/video_job.rb', line 83

def done?
  !pending?
end

#failed? ⇒ Boolean

Returns true when the job finished without a video. #error carries the provider's failure message.

Returns:

  • (Boolean) 


94
95
96
 
# File 'lib/ruby_llm/video_job.rb', line 94

def failed?
  status == :failed
end

#pending? ⇒ Boolean

Returns true while the provider is still rendering the video.

Returns:

  • (Boolean) 


78
79
80
 
# File 'lib/ruby_llm/video_job.rb', line 78

def pending?
  status == :pending
end

#refresh ⇒ Object

Re-fetches the job from the provider, updating #status, #error, and #raw. Does nothing once the job is #done?. Returns self.



100
101
102
103
104
105
106
107
108
 
# File 'lib/ruby_llm/video_job.rb', line 100

def refresh
  return self if done?

  state = @protocol.refresh_video_job(self)
  @status = state.fetch(:status)
  @raw = state[:raw]
  @error = state[:error]
  self
end

#video ⇒ Object

Returns the finished Video, downloading it from the provider when its API requires that. Returns nil while #pending? and raises Error when #failed?.

Raises:



133
134
135
136
137
138
 
# File 'lib/ruby_llm/video_job.rb', line 133

def video
  raise Error, "Video generation failed: #{error}" if failed?
  return unless completed?

  @video ||= @protocol.download_video(self).tap { |video| video.config = @protocol.config }
end

#wait(timeout: nil, interval: nil) ⇒ Object

Polls the job until it finishes, then returns self. Raises Error when the job fails or timeout elapses first. timeout and interval are seconds and default to the configured video_generation_timeout and video_generation_poll_interval.

Raises:



114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/ruby_llm/video_job.rb', line 114

def wait(timeout: nil, interval: nil)
  timeout ||= @protocol.config.video_generation_timeout
  interval ||= @protocol.config.video_generation_poll_interval
  deadline = monotonic_time + timeout

  until done?
    raise Error, "Video generation timed out after #{timeout} seconds" if monotonic_time > deadline

    sleep interval
    refresh
  end
  raise Error, "Video generation failed: #{error}" if failed?

  self
end