diff --git a/.github/workflows/ruby.yml b/.github/workflows/ruby.yml
index e1dca29..f4bc70b 100644
--- a/.github/workflows/ruby.yml
+++ b/.github/workflows/ruby.yml
@@ -15,6 +15,8 @@ jobs:
- uses: actions/checkout@v4
- name: Set up Ruby
uses: ruby/setup-ruby@v1
+ with:
+ ruby-version: '3.3'
- name: Install dependencies
run: bundle install
- name: Run tests
diff --git a/Gemfile.lock b/Gemfile.lock
index acdb79d..38304a1 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -1,7 +1,7 @@
PATH
remote: .
specs:
- htmlcsstoimage-api (0.5.0)
+ htmlcsstoimage-api (1.0.0)
addressable (> 2.5.0)
httparty (> 0.10)
diff --git a/README.md b/README.md
index c539de4..1a6656e 100644
--- a/README.md
+++ b/README.md
@@ -112,6 +112,107 @@ images = client.create_image_batch(
)
```
+## Recordings
+
+Record HTML/CSS or a public webpage as MP4, WebM, or GIF. Use
+`create_html_css_recording` for HTML/CSS and `create_url_recording` for a webpage:
+
+```ruby
+recording = client.create_url_recording(
+ "https://example.com",
+ duration_ms: 10000,
+ viewport_width: 1280,
+ viewport_height: 720,
+ actions: [{ type: "simple_scroll" }],
+ output: { format: "mp4" }
+)
+
+recording.id
+recording.status_url
+recording.recording_url
+
+animation = client.create_html_css_recording(
+ "
Hello
",
+ css: "@keyframes fade { from { opacity: 0; } to { opacity: 1; } } h1 { animation: fade 2s; font-family: Roboto; }",
+ google_fonts: "Roboto",
+ duration_ms: 3000,
+ duration_mode: "fixed",
+ output: { format: "gif", scale: 0.5 }
+)
+```
+
+Both methods accept browser, timeline, and output options as hashes, following
+the image methods. Options pass through to the API without local validation.
+Omitted settings use API defaults. Recordings do not include audio.
+
+Triggers and actions use a `type` discriminator. For example, wait until an
+element is visible, click a button, and hold the result:
+
+```ruby
+demo = client.create_url_recording(
+ "https://example.com/demo",
+ duration_ms: 5000,
+ duration_mode: "fixed",
+ trigger: { type: "element_visible", selector: "#demo", timeout_ms: 2000 },
+ actions: [
+ { type: "click", selector: "#start", if_not_found: [{ type: "error" }] },
+ { type: "stall", duration_ms: 1000 }
+ ]
+)
+```
+
+Nested branches run on the API. For JavaScript actions, omitting `if_error` or
+setting it to `nil` fails on a script error; `if_error: []` ignores errors.
+Empty arrays, explicit `nil`, `false`, and zero values are preserved in JSON.
+
+A `scroll` action moves through ordered `steps`. Each step's `duration_ms` is
+required and must be at least 1:
+
+```ruby
+client.create_url_recording(
+ "https://example.com",
+ duration_ms: 6000,
+ actions: [
+ { type: "scroll", steps: [
+ { to: { type: "selector", selector: "#pricing" }, duration_ms: 1200, easing: "ease_in_out_cubic" },
+ { to: { type: "position", position: "bottom" }, duration_ms: 1500 }
+ ] }
+ ]
+)
+```
+
+Embed or request `recording_url` directly; the request waits until the
+recording is ready, so checking status is optional. To inspect progress, fetch
+the current status once with:
+
+```ruby
+status = client.fetch_recording_status(recording.id)
+puts status.status
+puts status.attempt_count
+```
+
+HTTP 200 and 202 both return status information. The states `ready`, `failed`,
+and `cancelled` are terminal. A successful status fetch can report a failed
+recording, and `status.error` can describe an earlier, retryable attempt.
+`status.status` is the raw API string. Treat values not listed here, which
+newer API versions may add, as unknown; the client passes them through as-is.
+API errors and transport failures follow the existing image-method behavior.
+
+Delete recordings individually or in a batch:
+
+```ruby
+client.delete_recording("recording-id")
+client.delete_recording_batch(["first-id", "second-id"])
+```
+
+Deletion returns `true` when accepted, or the API response on failure. Empty
+batch lists succeed without an API request, matching `delete_image_batch`.
+
+See the [recording guide](https://docs.htmlcsstoimage.com/getting-started/recordings/),
+[actions reference](https://docs.htmlcsstoimage.com/parameters/actions/), and
+[trigger reference](https://docs.htmlcsstoimage.com/parameters/trigger/) for
+options and examples.
+
## Signed URLs
Signed URLs let another application, browser, or service render an image on
diff --git a/docs/HTMLCSSToImage.html b/docs/HTMLCSSToImage.html
index 5c7b0c8..274e89b 100644
--- a/docs/HTMLCSSToImage.html
+++ b/docs/HTMLCSSToImage.html
@@ -102,7 +102,7 @@
Records an HTML document or fragment with optional CSS and Google Fonts.
+Returns the recording ID, status URL, and media URL while rendering can
+continue in the background. Optional settings use the API defaults.
@@ -628,7 +762,7 @@
—
-
HTML to render, as a snippet or an entire webpage
+
HTML to record, as a fragment or a complete document
@@ -644,7 +778,7 @@
—
-
image creation options
+
browser, timeline, and output options passed to the API
The format used in the initially returned URL: png, jpg, webp, or pdf. This does not change the stored image definition or prevent rendering another supported format later.
+ —
Required recording duration in milliseconds: 500–30000, or up to 90000 in target mode.
@@ -676,18 +810,7 @@
- —
The CSS for your image.
-
-
-
-
- :device_scale
- (Numeric)
-
-
-
-
- —
The pixel ratio for the screenshot. Minimum: 0.1, Maximum: 3.
+ —
CSS used to style the recording.
@@ -698,238 +821,227 @@
- —
Google Fonts to load. Separate multiple fonts with |.
+ —
Google Fonts to load, separated by |. Set font-family in the CSS to use them.
Start condition: type: "immediate" (default), "element_visible" with a selector, or "function_call" to wait for window.RecordingReady(). Waiting triggers accept timeout_ms.
Ordered timeline interactions: simple_scroll, scroll, stall, click, locate_selector, execute_javascript, or error. Each action has a type discriminator. Omit or use an empty array to record without interactions.
- :proxy_id
- (String)
+ :output
+ (Hash)
- —
The ID of an organization proxy to use for the render.
+ —
Media format (mp4, webm, or gif), fps, and pixel scale. Defaults to MP4 at 30 fps; GIF defaults to 15 fps. Recordings have no audio.
The ID of an organization storage destination for the rendered image.
-
-
-
-
- :jumbo_max_height
- (Integer)
-
-
-
-
- —
Maximum output height in jumbo mode. Requires jumbo_max_width.
+ —
at_most (default) stops when actions finish or the duration is reached. fixed pads or cuts off at that duration. at_least lets actions finish up to 90 seconds. target adjusts playback speed to fit the duration.
The format used in the initially returned URL: png, jpg, webp, or pdf. This does not change the stored image definition or prevent rendering another supported format later.
+
+
+
+
+ :css
+ (String)
+
+
+
+
+ —
The CSS for your image.
+
+
+
+
+ :device_scale
+ (Numeric)
+
+
+
+
+ —
The pixel ratio for the screenshot. Minimum: 0.1, Maximum: 3.
+
+
+
+
+ :google_fonts
+ (String)
+
+
+
+
+ —
Google Fonts to load. Separate multiple fonts with |.
+
+
+
+
+ :max_wait_ms
+ (Integer)
+
+
+
+
+ —
The maximum time to wait before taking the screenshot. Minimum: 500, Maximum: 10000.
+
+
+
+
+ :ms_delay
+ (Integer)
+
+
+
+
+ —
Extra time in milliseconds to wait before taking the screenshot. Maximum: 10000.
+
+
+
+
+ :render_when_ready
+ (Boolean)
+
+
+
+
+ —
Wait until ScreenshotReady() is called from JavaScript before taking the screenshot.
+
+
+
+
+ :selector
+ (String)
+
+
+
+
+ —
A CSS selector for the element to capture.
+
+
+
+
+ :viewport_height
+ (Integer)
+
+
+
+
+ —
The Chrome viewport height. Both viewport dimensions must be set if using either.
+
+
+
+
+ :viewport_width
+ (Integer)
+
+
+
+
+ —
The Chrome viewport width. Both viewport dimensions must be set if using either.
+
+
+
+
+ :pdf_options
+ (Hash)
+
+
+
+
+ —
Options for generating a PDF, including page size, margins, scale, and background printing.
+
+
+
+
+ :disable_twemoji
+ (Boolean)
+
+
+
+
+ —
For HTML/CSS, true disables default Twemoji replacement. For URLs, only explicit false injects Twemoji; omitted or true leaves the page unchanged.
+
+
+
+
+ :max_render_once
+ (Boolean)
+
+
+
+
+ —
Ensure the image is only rendered and saved once.
+
+
+
+
+ :dedupe_duration_s
+ (Integer)
+
+
+
+
+ —
Reuse an identical image created within this many seconds. Only supported for single-image POST requests.
+
+
+
+
+ :color_scheme
+ (String)
+
+
+
+
+ —
Render using the light or dark browser color scheme.
+
+
+
+
+ :timezone
+ (String)
+
+
+
+
+ —
The browser timezone as an IANA timezone identifier, such as America/New_York.
+
+
+
+
+ :viewport_mobile
+ (Boolean)
+
+
+
+
+ —
Whether to honor the page's mobile viewport behavior.
+
+
+
+
+ :viewport_landscape
+ (Boolean)
+
+
+
+
+ —
Whether to render the viewport in landscape mode.
+
+
+
+
+ :viewport_touch
+ (Boolean)
+
+
+
+
+ —
Whether the viewport supports touch events.
+
+
+
+
+ :media_type
+ (String)
+
+
+
+
+ —
Render using print or screen media.
+
+
+
+
+ :proxy_id
+ (String)
+
+
+
+
+ —
The ID of an organization proxy to use for the render.
+
+
+
+
+ :request_overrides
+ (Array<Hash>)
+
+
+
+
+ —
Browser request block rules, such as { action: "block", resource_types: [RequestOverrideResourceType::Script] }. Requires a paid plan.
+
+
+
+
+ :storage_destination_id
+ (String)
+
+
+
+
+ —
The ID of an organization storage destination for the rendered image.
+
+
+
+
+ :jumbo_max_height
+ (Integer)
+
+
+
+
+ —
Maximum output height in jumbo mode. Requires jumbo_max_width.
+
+
+
+
+ :jumbo_max_width
+ (Integer)
+
+
+
+
+ —
Maximum output width in jumbo mode. Requires jumbo_max_height.
+
+
+
+
+ :transparent_background
+ (Boolean)
+
+
+
+
+ —
Whether to render the image with a transparent background.
Creates images from one or more templates in a single request.
+Objects in template_values merge recursively; arrays, scalars and null replace defaults.
+Supplying template_id resets the inherited version; omit a version to use latest.
@@ -1311,305 +2501,203 @@
- html
+ variations
- (String)
+ (Array<Hash>)
—
-
HTML for the template
+
per-image template options; results preserve this order
- params
+ default_options
- (Hash)
+ (Hash, nil)
- (defaults to: {})
+ (defaults to: nil)
—
-
template and rendering options
+
shared template_id, template_version, template_values and format
+
Returns:
+
-
-
-
-
-
Options Hash (params):
-
-
-
- :name
- (String)
-
-
-
-
- —
A short name to identify the template. Maximum length: 64.
-
-
-
-
- :description
- (String)
-
-
-
-
- —
A description of the template. Maximum length: 1024.
-
-
+
-
- :css
- (String)
-
-
-
-
- —
The CSS for the template.
-
-
-
- :device_scale
- (Numeric)
-
-
-
-
- —
The pixel ratio for the screenshot. Minimum: 0.1, Maximum: 3.
Fetches a recording's current lifecycle state once.
+HTTP 200 and 202 both return status information. The states ready,
+failed, and cancelled are terminal; an error can also describe an
+earlier, retryable attempt. Requesting the media URL waits for processing.
Both methods accept browser, timeline, and output options as hashes, following
+the image methods. Options pass through to the API without local validation.
+Omitted settings use API defaults. Recordings do not include audio.
+
Triggers and actions use a type discriminator. For example, wait until an
+element is visible, click a button, and hold the result:
Nested branches run on the API. For JavaScript actions, omitting if_error or
+setting it to nil fails on a script error; if_error: [] ignores errors.
+Empty arrays, explicit nil, false, and zero values are preserved in JSON.
+
Creation returns the recording URLs while rendering can continue in the
+background. Requesting recording_url waits for processing. Fetch the current
+status once with:
HTTP 200 and 202 both return status information. The states ready, failed,
+and cancelled are terminal. A successful status fetch can report a failed
+recording, and status.error can describe an earlier, retryable attempt.
+API errors and transport failures follow the existing image-method behavior.
Signed URLs let another application, browser, or service render an image on
demand without exposing your API key. Generating a signed URL does not make an
@@ -259,12 +324,24 @@
Contributing
License
The gem is available as open source under the terms of the MIT License.
Code of Conduct
-
Everyone interacting in the project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
+
Everyone interacting in the project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
+
Templated image batches
+
Create images from one or more templates with shared defaults and ordered variations:
Omitted fields inherit defaults. Supplying a template ID resets the inherited version; omit its version to use latest. Template value objects merge recursively on the API; arrays, scalars, and explicit null values replace defaults. Results preserve input order and identical images reuse existing assets. Each merged values object must be nonempty and satisfy its template's required variables.
Both methods accept browser, timeline, and output options as hashes, following
+the image methods. Options pass through to the API without local validation.
+Omitted settings use API defaults. Recordings do not include audio.
+
Triggers and actions use a type discriminator. For example, wait until an
+element is visible, click a button, and hold the result:
Nested branches run on the API. For JavaScript actions, omitting if_error or
+setting it to nil fails on a script error; if_error: [] ignores errors.
+Empty arrays, explicit nil, false, and zero values are preserved in JSON.
+
Creation returns the recording URLs while rendering can continue in the
+background. Requesting recording_url waits for processing. Fetch the current
+status once with:
HTTP 200 and 202 both return status information. The states ready, failed,
+and cancelled are terminal. A successful status fetch can report a failed
+recording, and status.error can describe an earlier, retryable attempt.
+API errors and transport failures follow the existing image-method behavior.
Signed URLs let another application, browser, or service render an image on
demand without exposing your API key. Generating a signed URL does not make an
@@ -259,12 +324,24 @@
Contributing
License
The gem is available as open source under the terms of the MIT License.
Code of Conduct
-
Everyone interacting in the project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
+
Everyone interacting in the project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
+
Templated image batches
+
Create images from one or more templates with shared defaults and ordered variations:
Omitted fields inherit defaults. Supplying a template ID resets the inherited version; omit its version to use latest. Template value objects merge recursively on the API; arrays, scalars, and explicit null values replace defaults. Results preserve input order and identical images reuse existing assets. Each merged values object must be nonempty and satisfy its template's required variables.