- Notifications
You must be signed in to change notification settings - Fork4
Ruby SDK for Shotstack, the cloud video editing API.
shotstack/shotstack-sdk-ruby
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Ruby SDK for the ShotstackRuby video editor and cloud video editing API.
Shotstack is a cloud based video editing platform that enables the editing of videos using code.
The platform uses an API and a JSON format for specifying how videos should be edited and what asset and titles should be used.
A server based render farm takes care of rendering the videos allowing multiple videos to be created simultaneously.
For examples of how to use the SDK to create videos using code checkout the Ruby demo repo:https://github.com/shotstack/ruby-demos
- Using the Ruby SDK
- API Documentation and Guides
gem install shotstack
The Shotstack SDK enables programmatic video editing via the Edit APIrender endpoint. Prepare JSON edits using theprovided schema classes andPOST to the API for rendering.
The example below trims the start of a video clip and plays it for 8 seconds. The edit is prepared using the SDK modelsand then sent to the API for rendering.
require"shotstack"Shotstack.configuredo |config|config.api_key['x-api-key']="H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD"config.host="api.shotstack.io"config.base_path="stage"endapi_client=Shotstack::EditApi.newvideo_asset=Shotstack::VideoAsset.new(src:"https://s3-ap-southeast-2.amazonaws.com/shotstack-assets/footage/skater.hd.mp4",trim:3)video_clip=Shotstack::Clip.new(asset:video_asset,start:0,length:8)track=Shotstack::Track.new(clips:[video_clip])timeline=Shotstack::Timeline.new(background:"#000000",tracks:[track])output=Shotstack::Output.new(format:"mp4",resolution:"sd")edit=Shotstack::Edit.new(timeline:timeline,output:output)response=api_client.post_render(edit).responseputsresponse.id
The example request below can be called a few seconds after the render above is posted. It will return the status ofthe render, which can take several seconds to process.
require"shotstack"Shotstack.configuredo |config|config.api_key['x-api-key']="H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD"config.host="api.shotstack.io"config.base_path="stage"endid="75143ec6-4b72-46f8-a67a-fd7284546935"# Use the render id from the previous exampleapi_client=Shotstack::EditApi.newresponse=api_client.get_render(id,{data:false,merged:true}).responseifresponse.status ==="done"putsresponse.url
The example below uses the Edit we create in theVideo Editing Example and saves it as atemplate. The template can be rendered at a later date and can include placeholders. Placeholders can be replacedwhen rendered usingmerge fields.
This example uses a placeholder for the video src (URL), trim (TRIM), and length (LENGTH) to allow you to trim any videousing a template.
require"shotstack"Shotstack.configuredo |config|config.api_key['x-api-key']="H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD"config.host="api.shotstack.io"config.base_path="stage"endapi_client=Shotstack::EditApi.newvideo_asset=Shotstack::VideoAsset.new(src:"{{URL}}",trim:"{{TRIM}}")video_clip=Shotstack::Clip.new(asset:video_asset,start:0,length:"{{LENGTH}}")track=Shotstack::Track.new(clips:[video_clip])timeline=Shotstack::Timeline.new(background:"#000000",tracks:[track])output=Shotstack::Output.new(format:"mp4",resolution:"sd")edit=Shotstack::Edit.new(timeline:timeline,output:output)template=Shotstack::Template.new(name:"Trim Template",template:edit)response=api_client.post_template(template).responseputsresponse.id
The example below renders the template we created in the previous example and includes merge fields that will replacethe placeholders. Once submitted use the returned render ID and call theStatus Check Exampleto get the render progress.
require"shotstack"Shotstack.configuredo |config|config.api_key['x-api-key']="H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD"config.host="api.shotstack.io"config.base_path="stage"endid="8aeabb0e-b5eb-8c5e-847d-82297dd4802a";# use the template id from previous exampleapi_client=Shotstack::EditApi.newmerge_field_url=Shotstack::MergeField.new(find:"URL",replace:"https://s3-ap-southeast-2.amazonaws.com/shotstack-assets/footage/skater.hd.mp4")merge_field_trim=Shotstack::MergeField.new(find:"TRIM",replace:3)merge_field_length=Shotstack::MergeField.new(find:"LENGTH",replace:6)template=Shotstack::TemplateRender.new(id:id,merge:[merge_field_url,merge_field_trim,merge_field_length])response=api_client.post_template_render(template).responseputsresponse.id
The following schemas are used to prepare a video edit.
AnEdit defines the arrangement of a video on a timeline, an audio edit or an image design and the output format.
require"shotstack"edit=Shotstack::Edit.new(timeline:timeline,output:output,merge:merge,callback:"https://my-server.com/callback.php",disk:"local")
| Argument | Type | Description | Required |
|---|---|---|---|
| timeline | Shotstack::Timeline | A timeline represents the contents of a video edit over time, an audio edit over time, in seconds, or an image layout. A timeline consists of layers called tracks. Tracks are composed of titles, images, audio, html or video segments referred to as clips which are placed along the track at specific starting point and lasting for a specific amount of time. | - |
| output | Shotstack::Output | The output format, render range and type of media to generate. | Y |
| merge | Shotstack::MergeField[] | An array of key/value pairs that provides an easy way to create templates with placeholders. The placeholders can be used to find and replace keys with values. For example you can search for the placeholder{{NAME}} and replace it with the valueJane. | - |
| callback | string | An optional webhook callback URL used to receive status notifications when a render completes or fails. Seewebhooks for more details. | - |
| disk | string | (Deprecated) The disk type to use for storing footage and asset for each render. Seedisk types for more details. [default tolocal]
| - |
ATimeline represents the contents of a video edit over time, an audio edit over time, in seconds, or an image layout. A timeline consists of layers called tracks. Tracks are composed of titles, images, audio, html or video segments referred to as clips which are placed along the track at specific starting point and lasting for a specific amount of time.
require"shotstack"timeline=Shotstack::Timeline.new(soundtrack:soundtrack,background:'#000000',fonts:fonts,tracks:tracks,cache:true)
| Argument | Type | Description | Required |
|---|---|---|---|
| soundtrack | Shotstack::Soundtrack | A music or audio soundtrack file in mp3 format. | - |
| background | string | A hexadecimal value for the timeline background colour. Defaults to#000000 (black). | - |
| fonts | Shotstack::Font[] | An array of custom fonts to be downloaded for use by the HTML assets. | - |
| tracks | Shotstack::Track[] | A timeline consists of an array of tracks, each track containing clips. Tracks are layered on top of each other in the same order they are added to the array with the top most track layered over the top of those below it. Ensure that a track containing titles is the top most track so that it is displayed above videos and images. | Y |
| cache | bool | Disable the caching of ingested source footage and assets. Seecaching for more details. [default totrue] | - |
A music or audio file in mp3 format that plays for the duration of the rendered video or the length of the audio file, which ever is shortest.
require"shotstack"soundtrack=Shotstack::Soundtrack.new(src:'https://s3-ap-southeast-2.amazonaws.com/shotstack-assets/music/disco.mp3',effect:'fadeIn',volume:1)
| Argument | Type | Description | Required |
|---|---|---|---|
| src | string | The URL of the mp3 audio file. The URL must be publicly accessible or include credentials. | Y |
| effect | string | The effect to apply to the audio file
| - |
| volume | float | Set the volume for the soundtrack between 0 and 1 where 0 is muted and 1 is full volume (defaults to1). | - |
Download a custom font to use with the HTML asset type, using the font name in the CSS or font tag. See ourcustom fonts getting started guide for more details.
require"shotstack"font=Shotstack::Font.new(src:'https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/fonts/OpenSans-Regular.ttf')
| Argument | Type | Description | Required |
|---|---|---|---|
| src | string | The URL of the font file. The URL must be publicly accessible or include credentials. | Y |
A track contains an array of clips. Tracks are layered on top of each other in the order in the array. The top most track will render on top of those below it.
require"shotstack"track=Shotstack::Track(clips:clips)
| Argument | Type | Description | Required |
|---|---|---|---|
| clips | Shotstack::Clip[] | An array of Clips comprising of TitleClip, ImageClip or VideoClip. | Y |
AClip is a container for a specific type of asset, i.e. a title, image, video, audio or html. You use a Clip to define when an asset will display on the timeline, how long it will play for and transitions, filters and effects to apply to it.
require"shotstack"clip=Shotstack::Clip.new(asset:asset,start:2,length:5,fit:'crop',scale:0,position:'center',offset:offset,transition:transition,effect:'zoomIn',filter:'greyscale',opacity:1,transform:transform)
| Argument | Type | Description | Required |
|---|---|---|---|
| asset | asset | The type of asset to display for the duration of this Clip. Value must be one of: | Y |
| start | float | The start position of the Clip on the timeline, in seconds. | Y |
| length | float | The length, in seconds, the Clip should play for. | Y |
| fit | string fit | Set how the asset should be scaled to fit the viewport using one of the following options [default tocrop]:
| - |
| scale | float | Scale the asset to a fraction of the viewport size - i.e. ting the scale to 0.5 will scale asset to half the size of the viewport. This is useful for picture-in-picture video and scaling images such as logos and watermarks. | - |
| position | string | Place the asset in one of nine predefined positions of the viewport. This is most effective for when the asset is scaled and you want to position the element to a specific position [default tocenter].
| - |
| offset | Shotstack::Offset | Offset the location of the asset relative to its position on the viewport. The offset distance is relative to the width of the viewport - for example an x offset of 0.5 will move the asset half the viewport width to the right. | - |
| transition | Shotstack::Transition | In and out transitions for a clip - i.e. fade in and fade out | - |
| effect | string | A motion effect to apply to the Clip.
Fast orSlow to the effect, e.g.zoomInFast orslideRightSlow. | - |
| filter | string | A filter effect to apply to the Clip.
| - |
| opacity | float | s the opacity of the Clip where 1 is opaque and 0 is transparent. [default to1] | - |
| transform | Shotstack::Transformation | A transformation lets you modify the visual properties of a clip. Available transformations areShotstack::RotateTransformation,Shotstack::SkewTransformation andShotstack::FlipTransformation. Transformations can be combined to create interesting new shapes and effects. | - |
TheVideoAsset is used to create video sequences from video files. The src must be a publicly accessible URL to a videoresource such as an mp4 file.
require"shotstack"video_asset=Shotstack::VideoAsset.new(src:'https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/footage/table-mountain.mp4',trim:5,volume:0.5,volume_effect:'fadeIn',crop:crop)
| Argument | Type | Description | Required |
|---|---|---|---|
| src | string | The video source URL. The URL must be publicly accessible or include credentials. | Y |
| trim | float | The start trim point of the video clip, in seconds (defaults to 0). Videos will start from the in trim point. The video will play until the file ends or the Clip length is reached. | - |
| volume | float | Set the volume for the video clip between 0 and 1 where 0 is muted and 1 is full volume (defaults to 0). | - |
| volume_effect | string | The volume effect to apply to the video asset.
| - |
| crop | Shotstack::Crop | Crop the sides of an asset by a relative amount. The size of the crop is specified using a scale between 0 and 1, relative to the screen width - i.e. a left crop of 0.5 will crop half of the asset from the left, a top crop of 0.25 will crop the top by quarter of the asset. | - |
TheImageAsset is used to create video from images to compose an image. The src must be a publicly accessible URL to an image resource such as a jpg or png file.
require"shotstack"image_asset=Shotstack::ImageAsset.new(src:'https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/images/earth.jpg',crop:crop)
| Argument | Type | Description | Required |
|---|---|---|---|
| src | string | The image source URL. The URL must be publicly accessible or include credentials. | Y |
| crop | Shotstack::Crop | Crop the sides of an asset by a relative amount. The size of the crop is specified using a scale between 0 and 1, relative to the screen width - i.e. a left crop of 0.5 will crop half of the asset from the left, a top crop of 0.25 will crop the top by quarter of the asset. | - |
TheTitleAsset clip type lets you create video titles from a text string and apply styling and positioning.
require"shotstack"title_asset=Shotstack::TitleAsset.new(text:'My Title',style:'minimal',color:'#ffffff',size:'medium',background:'#000000',position:'center',offset:offset)
| Argument | Type | Description | Required |
|---|---|---|---|
| text | string | The title text string. | Y |
| style | string | Uses a preset to apply font properties and styling to the title.
| - |
| color | string | Set the text color using hexadecimal color notation. Transparency is supported by ting the first two characters of the hex string (opposite to HTML), i.e. #80ffffff will be white with 50% transparency [default to#ffffff]. | - |
| size | string | Set the relative size of the text using predefined sizes from xx-small to xx-large [default to 'medium'].
| - |
| background | string | Apply a background color behind the text. Set the text color using hexadecimal color notation. Transparency is supported by ting the first two characters of the hex string (opposite to HTML), i.e. #80ffffff will be white with 50% transparency. Omit to use transparent background. | - |
| position | string | Place the title in one of nine predefined positions of the viewport [default tocenter.
| - |
| offset | Shotstack::Offset | Offset the location of the title relative to its position on the screen. | - |
TheHtmlAsset clip type lets you create text based layout and formatting using HTML and CSS. You can also set the height and width of a bounding box for the HTML content to sit within. Text and elements will wrap within the bounding box.
require"shotstack"html_asset=Shotstack::HtmlAsset.new(html:'<p>Hello <b>World</b></p>',css:'p { color: #ffffff; } b { color: #ffff00; }',width:400,height:200,background:'transparent',position:'center')
Argument | Type | Description | Required:--- | :--- | :---:html | string | The HTML text string. See list ofsupported HTML tags. | Ycss | string | The CSS text string to apply styling to the HTML. See list ofsupport CSS properties. | -width | int | Set the width of the HTML asset bounding box in pixels. Text will wrap to fill the bounding box. | -height | int | Set the height of the HTML asset bounding box in pixels. Text and elements will be masked if they exceed the height of the bounding box. | -background | string | Apply a background color behind the HTML bounding box using. Set the text color using hexadecimal color notation. Transparency is supported by ting the first two characters of the hex string (opposite to HTML), i.e. #80ffffff will be white with 80% transparency [default totransparent]. | -position | string | Place the HTML in one of nine predefined positions within the HTML area [default tocenter].
top- top (center)topRight- top rightright- right (center)bottomRight- bottom rightbottom- bottom (center)bottomLeft- bottom leftleft- left (center)topLeft- top leftcenter- center
TheAudioAsset is used to add sound effects and audio at specific intervals on the timeline. The src must be apublicly accessible URL to an audio resource such as an mp3 file.
require"shotstack"audio_asset=Shotstack::AudioAsset.new(src:'https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/music/unminus/lit.mp3',trim:2,volume:0.5,effect:'fadeInFadeOut')
| Argument | Type | Description | Required |
|---|---|---|---|
| src | string | The audio source URL. The URL must be publicly accessible or include credentials. | Y |
| trim | float | The start trim point of the audio clip, in seconds (defaults to 0). Audio will start from the trim point. The audio will play until the file ends or the Clip length is reached. | - |
| volume | float | Set the volume for the audio clip between 0 and 1 where 0 is muted and 1 is full volume (defaults to 1). | - |
| effect | string | The effect to apply to the audio asset:
| - |
TheLumaAsset is used to create luma matte masks, transitions and effects between other assets. A luma matte is a grey scale image or animated video where the black areas are transparent and the white areas solid. The luma matte animation should be provided as an mp4 video file. The src must be a publicly accessible URL to the file.
require"shotstack"luma_asset=Shotstack::LumaAsset.new(src:'https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/examples/luma-mattes/paint-left.mp4',trim:5)
| Argument | Type | Description | Required |
|---|---|---|---|
| src | string | The luma matte source URL. The URL must be publicly accessible or include credentials. | Y |
| trim | float | The start trim point of the luma matte clip, in seconds (defaults to 0). Videos will start from the in trim point. A luma matte video will play until the file ends or the Clip length is reached. | - |
TheTransition clip type lets you define in and out transitions for a clip - i.e. fade in and fade out
require"shotstack"transition=Shotstack::Transition.new(in:'fade',out:'fade')
| Argument | Type | Description | Required |
|---|---|---|---|
| in | string | The transition in. Available transitions are:
Fast orSlow to the transition, e.g.fadeFast orCarouselLeftSlow. | - |
| out | string | The transition out. Available transitions are:
Fast orSlow to the transition, e.g.fadeFast orCarouselLeftSlow. | - |
Offs the position of an asset horizontally or vertically by a relative distance.
require"shotstack"offset=Shotstack::Offset.new(x:0.1,y: -0.2)
| Argument | Type | Description | Required |
|---|---|---|---|
| x | float | Offset an asset on the horizontal axis (left or right), range varies from -10 to 10. Positive numbers move the asset right, negative left. For all asset except titles the distance moved is relative to the width of the viewport - i.e. an X offset of 0.5 will move the asset half the screen width to the right. [default to0] | - |
| y | float | Offset an asset on the vertical axis (up or down), range varies from -10 to 10. Positive numbers move the asset up, negative down. For all asset except titles the distance moved is relative to the height of the viewport - i.e. an Y offset of 0.5 will move the asset up half the screen height. [default to0] | - |
Crop the sides of an asset by a relative amount. The size of the crop is specified using a scale between 0 and 1, relative to the screen width - i.e a left crop of 0.5 will crop half of the asset from the left, a top crop of 0.25 will crop the top by quarter of the asset.
require"shotstack"crop=Shotstack::Crop.new(top:0.15,bottom:0.15,left:0,right:0)
| Argument | Type | Description | Required |
|---|---|---|---|
| top | float | Crop from the top of the asset | - |
| bottom | float | Crop from the bottom of the asset | - |
| left | float | Crop from the left of the asset | - |
| right | float | Crop from the right of the asset | - |
Apply one or more transformations to a clip.Transformations alter the visual properties of a clip and can be combined to create new shapes and effects.
require"shotstack"transformation=Shotstack::Transformation.new(rotate:rotate,skew:skew,flip:flip)
| Argument | Type | Description | Required |
|---|---|---|---|
| rotate | Shotstack::RotateTransformation | Rotate a clip by the specified angle in degrees. Rotation origin is set based on the clipsposition. | - |
| skew | Shotstack::SkewTransformation | Skew a clip so its edges are sheared at an angle. Use values between 0 and 3. Over 3 the clip will be skewed almost flat. | - |
| flip | Shotstack::FlipTransformation | Flip a clip vertically or horizontally. Acts as a mirror effect of the clip along the selected plane. | - |
Rotate a clip by the specified angle in degrees. Rotation origin is set based on the clipsposition.
require"shotstack"rotate_transformation=Shotstack::RotateTransformation.new(angle:45)
| Argument | Type | Description | Required |
|---|---|---|---|
| angle | int | The angle to rotate the clip. Can be 0 to 360, or 0 to -360. Using a positive number rotates the clip clockwise, negative numbers counter-clockwise. | - |
Skew a clip so its edges are sheared at an angle. Use values between 0 and 3. Over 3 the clip will be skewed almost flat.
require"shotstack"skew_transformation=Shotstack::SkewTransformation.new(x:0.5,y:0.5)
| Argument | Type | Description | Required |
|---|---|---|---|
| x | float | Skew the clip along it's x axis. [default to0] | - |
| y | float | Skew the clip along it's y axis. [default to0] | - |
Flip a clip vertically or horizontally. Acts as a mirror effect of the clip along the selected plane.
require"shotstack"flip_transformation=Shotstack::FlipTransformation.new(horizontal:true,vertical:true)
| Argument | Type | Description | Required |
|---|---|---|---|
| horizontal | bool | Flip a clip horizontally. [default tofalse] | - |
| vertical | bool | Flip a clip vertically. [default tofalse] | - |
A merge field consists of a key;find, and avalue; replace. Merge fields can be used to replace placeholders within the JSON edit to create re-usable templates. Placeholders should be a string with double brace delimiters, i.e."{{NAME}}". A placeholder can be used for any value within the JSON edit.
require"shotstack"merge_field=Shotstack::MergeField.new(find:'NAME',replace:'Jane')
| Argument | Type | Description | Required |
|---|---|---|---|
| find | string | The string to find without delimiters. | Y |
| replace | replace | The replacement value. The replacement can be any valid JSON type - string, boolean, number, etc... | Y |
The following schemas specify how to use templates to store and render templates. A template lets you save anEdit that can be rendered by its template ID and optionally include merge fields that are merged with thetemplate when rendered.
A template is a savedEdit than can be loaded and re-used.
require"shotstack"template=Shotstack::Template.new(name:'My Template',template:edit)
| Argument | Type | Description | Required |
|---|---|---|---|
| name | string | The template name. | Y |
| template | Shotstack::Edit | An edit defines the arrangement of a video on a timeline, an audio edit or an image design and the output format. | Y |
Configure the id and optional merge fields to render a template by id.
require"shotstack"template=Shotstack::TemplateRender.new(id:'21e781c0-8232-4418-fec1-cc99f0280c21',merge:merge)
| Argument | Type | Description | Required |
|---|---|---|---|
| id | string | The id of the template to render in UUID format. | Y |
| merge | Shotstack::MergeField[] | An array of key/value pairs that provides an easy way to create templates with placeholders. The placeholders can be used to find and replace keys with values. For example you can search for the placeholder{{NAME}} and replace it with the valueJane. | - |
The following schemas specify the output format and tings.
The output format, render range and type of media to generate.
require"shotstack"output=Shotstack::Output.new(format:'mp4',resolution:'sd',aspectRatio:'16:9',size:size,fps:25,scale_to:'preview',quality:'medium',repeat:true,mute:false,range:range,poster:poster,thumbnail:thumbnail,destinations:destinations)
| Argument | Type | Description | Required |
|---|---|---|---|
| format | string | The output format and type of media file to generate.
| Y |
| resolution | string | The output resolution of the video or image.
| - |
| aspectRatio | string | The aspect ratio (shape) of the video or image. Useful for social media output formats. Options are:
| - |
| size | Shotstack::Size | Set a custom size for a video or image. When using a custom size omit theresolution andaspectRatio. Custom sizes must be divisible by 2 based on the encoder specifications. | - |
| fps | float | Override the default frames per second. Useful for when the source footage is recorded at 30fps, i.e. on mobile devices. Lower frame rates can be used to add cinematic quality (24fps) or to create smaller file size/faster render times or animated gifs (12 or 15fps). Default is 25fps.
| - |
| scaleTo | string | Override the resolution and scale the video or image to render at a different size. When using scaleTo the asset should be edited at the resolution dimensions, i.e. use font sizes that look best at HD, then use scaleTo to output the file at SD and the text will be scaled to the correct size. This is useful if you want to create multiple asset sizes.
| - |
| quality | string | Adjust the output quality of the video, image or audio. Adjusting quality affects render speed, download speeds and storage requirements due to file size. The defaultmedium provides the most optimized choice for all three factors.
| - |
| repeat | bool | Loop tings for gif files. Set totrue to loop,false to play only once. [default totrue] | - |
| mute | bool | Mute the audio track of the output video. Set totrue to mute,false to un-mute. | - |
| range | Shotstack::Range | Specify a time range to render, i.e. to render only a portion of a video or audio file. Omit this ting to export the entire video. Range can also be used to render a frame at a specific time point - ting a range and output format asjpg will output a single frame image at the rangestart point. | - |
| poster | Shotstack::Poster | Generate a poster image from a specific point on the timeline. | - |
| thumbnail | Shotstack::Thumbnail | Generate a thumbnail image from a specific point on the timeline. | - |
| destinations | Shotstack::Destinations[] | A destination is a location where output files can be sent to for serving or hosting. By default all rendered assets are automatically sent to the Shotstack hosting destination. | - |
Set a custom size for a video or image. When using a custom size omit theresolution andaspectRatio. Custom sizes must be divisible by 2 based on the encoder specifications.
require"shotstack"size=Shotstack::Size.new(width:1200,height:800)
| Argument | Type | Description | Required |
|---|---|---|---|
| width | int | Set a custom width for the video or image file. Value must be divisible by 2. Maximum video width is 1920px, maximum image width is 4096px. | - |
| height | int | Set a custom height for the video or image file. Value must be divisible by 2. Maximum video height is 1920px, maximum image height is 4096px. | - |
Specify a time range to render, i.e. to render only a portion of a video or audio file. Omit this ting to export the entire video. Range can also be used to render a frame at a specific time point - ting a range and output format asjpg will output a single frame image at the rangestart point.
require"shotstack"range=Shotstack::Range.new(start:3,length:6)
| Argument | Type | Description | Required |
|---|---|---|---|
| start | float | The point on the timeline, in seconds, to start the render from - i.e. start at second 3. | - |
| length | float | The length of the portion of the video or audio to render - i.e. render 6 seconds of the video. | - |
Generate aPoster image for the video at a specific point from the timeline. The poster image size will match the size of the output video.
require"shotstack"poster=Shotstack::Poster.new(capture:1)
| Argument | Type | Description | Required |
|---|---|---|---|
| capture | float | The point on the timeline in seconds to capture a single frame to use as the poster image. | Y |
Generate a thumbnail image for the video or image at a specific point from the timeline.
require"shotstack"thumbnail=Shotstack::Thumbnail.new(capture:1,scale:0.3)
| Argument | Type | Description | Required |
|---|---|---|---|
| capture | float | The point on the timeline in seconds to capture a single frame to use as the thumbnail image. | Y |
| scale | float | Scale the thumbnail size to a fraction of the viewport size - i.e. ting the scale to 0.5 will scale the thumbnail to half the size of the viewport. | Y |
Send rendered asset to the Shotstack hosting and CDN service. This destination is enabled by default.
require"shotstack"shotstack_destination=Shotstack::ShotstackDestination.new(provider:'shotstack',exclude:false)
| Argument | Type | Description | Required |
|---|---|---|---|
| provider | string | The destination to send rendered assets to - set toshotstack for Shotstack. | Y |
| exclude | bool | Set totrue to opt-out from the Shotstack hosting and CDN service. All files must be downloaded within 24 hours of rendering. [default tofalse] | - |
Send rendered videos to theMux video hosting andstreaming service. Mux credentials are required and added via thedashboard, not in the request.
require"shotstack"mux_destination=Shotstack::MuxDestination.new(provider:'mux',options:mux_destination_options)
| Argument | Type | Description | Required |
|---|---|---|---|
| provider | string | The destination to send rendered assets to - set tomux for Mux. | Y |
| options | Shotstack::MuxDestinationOptions | Additional Mux configuration and features. | - |
Pass additional options to control how Mux processes video. Currently supports playback policy option.
mux_destination_options = Shotstack::MuxDestinationOptions.new(playback_policy: ['public'])
#### Arguments:Argument | Type | Description | Required:--- | :--- | :--- | :---: playback_policy | [string] | Sets the Mux `playback_policy` option. Value is an array of strings - use **public**, **signed**, or both. | - ### S3DestinationSend rendered videos to an [Amazon S3](https://shotstack.io/docs/guide/serving-assets/destinations/s3) bucket. Send files to any region with your own prefix and filename. AWS credentials are required and added via the [dashboard](https://dashboard.shotstack.io/integrations/s3), not in the request.#### Example:```pythonrequire "shotstack"const s3_destination = new Shotstack::S3Destination.new( provider: 's3', options: S3_destination_options)| Argument | Type | Description | Required |
|---|---|---|---|
| provider | string | The destination to send rendered assets to - set tos3 for S3. | Y |
| options | S3DestinationOptions | Additional S3 configuration options. | - |
Pass additional options to control how files are stored in S3.
require"shotstack"consts3_destination_options=newShotstack::S3DestinationOptions.new(region:'us-east-1',bucket:'my-bucket',prefix:'my-renders',filename:'my-file',acl:'public-read',)
| Argument | Type | Description | Required |
|---|---|---|---|
| region | string | Choose the region to send the file to. Must be a validAWS region string likeus-east-1 orap-southeast-2 | Y |
| bucket | string | The bucket name to send files to. The bucket must exist in the AWS account before files can be sent. | Y |
| prefix | string | A prefix for the file being sent. This is typically a folder name, i.e.videos orcustomerId/videos. | - |
| filename | string | Use your own filename instead of the default render ID filename. Note: omit the file extension as this will be appended depending on the output format. Also-poster.jpg and-thumb.jpg will be appended for poster and thumbnail images. | - |
| acl | string | Sets the S3 Access Control List (acl) permissions. Default isprivate. Must use a valid S3Canned ACL. | - |
The following schemas are returned by the render request and status request.
The response received after arender request is submitted. The render task is queued for rendering and a unique render id is returned.
| Attribute | Type | Description | Required |
|---|---|---|---|
| success | bool | true if successfully queued, elsefalse. | Y |
| message | string | Created,Bad Request or an error message. | Y |
| response | Shotstack::QueuedResponseData | QueuedResponseData or an error message. | Y |
TheQueuedResponseData is the response data returned with theQueuedResponse.
| Attribute | Type | Description | Required |
|---|---|---|---|
| message | string | Success response message or error details. | Y |
| id | string | The id of the render task in UUID format. | Y |
TheRenderResponse is the response received after arender status request is submitted. The response includes details about status of a render and the output URL.
| Attribute | Type | Description | Required |
|---|---|---|---|
| success | bool | true if status available, elsefalse. | Y |
| message | string | OK or an error message. | Y |
| response | Shotstack::RenderResponseData | RenderResponse or an error message. | Y |
TheRenderResponseData is the response data returned with theRenderResponse request including status and URL.
| Argument | Type | Description | Required |
|---|---|---|---|
| id | string | The id of the render task in UUID format. | Y |
| owner | string | The owner id of the render task. | Y |
| plan | string | The customer subscription plan. | - |
| status | string | The status of the render task.
| Y |
| error | string | An error message, only displayed if an error occurred. | - |
| duration | float | The output video or audio length in seconds. | - |
| render_time | float | The time taken to render the asset in milliseconds. | - |
| url | string | The URL of the final asset. This will only be available if status is done. This is a temporary URL and will be deleted after 24 hours. By default all asset are copied to the Shotstack hosting and CDN destination. | - |
| poster | string | The URL of the poster image if requested. This will only be available if status is done. | - |
| thumbnail | string | The URL of the thumbnail image if requested. This will only be available if status is done. | - |
| data | Shotstack::Edit | The timeline and output data to be rendered. | Y |
| created | string | The time the render task was initially queued. | Y |
| updated | string | The time the render status was last updated. | Y |
The following schemas are returned by the templates endpoint, including create, update and rendering a template.
The response received after atemplate is submitted. The template is saved and a uniquetemplate id is returned.
| Argument | Type | Description | Required |
|---|---|---|---|
| success | bool | true if successfully created, elsefalse. | Y |
| message | string | Created,Bad Request or an error message. | Y |
| response | Shotstack::TemplateResponseData | TemplateResponseData or an error message. | Y |
The response data returned with theShotstack.TemplateResponse.
| Argument | Type | Description | Required |
|---|---|---|---|
| message | string | Success response message or error details. | Y |
| id | string | The unique id of the template in UUID format. | Y |
The template data including the template name andEdit.
| Argument | Type | Description | Required |
|---|---|---|---|
| success | bool | true if successfully returned, elsefalse. | Y |
| message | string | OK,Bad Request or an error message. | Y |
| response | Shotstack::TemplateDataResponseData | TemplateDataResponseData or an error message. | Y |
The response data returned with theTemplateDataResponse.
| Argument | Type | Description | Required |
|---|---|---|---|
| id | string | The unique id of the template in UUID format. | Y |
| name | string | The template name. | Y |
| owner | string | The owner id of the templates. | Y |
| templateShotstack::Edit | Edit or an error message. | Y |
A list of previously saved templates.
| Argument | Type | Description | Required |
|---|---|---|---|
| success | bool | true if successfully returned, elsefalse. | Y |
| message | string | OK,Bad Request or an error message. | Y |
| response | Shotstack::TemplateListResponseData | TemplateListResponseData or an error message. | Y |
The response data returned with theTemplateListResponse.
| Argument | Type | Description | Required |
|---|---|---|---|
| owner | bool | The owner id of the templates. | Y |
| templates | Shotstack::TemplateListResponseItem[] | The list of templates. | Y |
The individual template item returned with theTemplateListResponseData templateslist.
| Argument | Type | Description | Required |
|---|---|---|---|
| id | string | The unique id of the template in UUID format. | Y |
| name | string | The template name | Y |
| created | string | The time the template was created. | - |
| updated | string | The time the template was last updated. | - |
The SDKprobe endpoint can be used to inspect media hosted online. Simply pass the URL of an asset to inspect.
The example below inspects (probes) a video hosted on GitHub and returns metadata about the file.
require"shotstack"Shotstack.configuredo |config|config.api_key['x-api-key']="H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD"config.host="api.shotstack.io"config.base_path="stage"endurl="https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4"api_client=Shotstack::EditApi.newbeginresponse=api_client.probe(url).responserescue=>errorabort("Request failed:#{error.message}")endresponse[:metadata][:streams].each_with_indexdo |stream,index|ifstream[:codec_type] ==='video'puts"Example settings for:#{response[:metadata][:format][:filename]}"puts"Width:#{stream[:width]}px"puts"Height:#{stream[:height]}px"puts"Framerate:#{stream[:r_frame_rate]} fps"puts"Duration:#{stream[:duration]} secs"endend
The following schemas are returned by the probe request.
TheProbeResponse is the response returned after aprobe request is submitted. The probe requests returns data from FFprobe formatted as JSON.
| Argument | Type | Description | Required |
|---|---|---|---|
| success | bool | true if media successfully read, elsefalse. | Y |
| message | string | Created,Bad Request or an error message. | Y |
| response | object | The response from FFprobe in JSON format | Y |
By default, all assets generated by the editing API are hosted by Shotstack and served via our CDN. The SDK providesaccess to the Serve API to retrieve information about hosted files. Files can also be deleted.
The example below uses a render ID to look up hosted assets associated with the render. Note that multiple assets can becreated for a render, i.e. video, thumb and poster. Each asset has a unique asset ID different to the render ID.
require"shotstack"Shotstack.configuredo |config|config.api_key['x-api-key']="H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD"config.host="api.shotstack.io"config.base_path="serve/stage"endid="140924c6-077d-4334-a89f-94befcfc0155"api_client=Shotstack::ServeApi.newbegindata=api_client.get_asset_by_render_id(id).datarescue=>errorabort("Request failed:#{error.message}")enddata.eachdo |asset|caseasset.attributes.statuswhen"failed"puts">> Something went wrong, asset could not be copied."elseputs"Status:#{asset.attributes.status}"puts">> Asset CDN URL:#{asset.attributes.url}"puts">> Asset ID:#{asset.attributes.id}"puts">> Render ID:#{asset.attributes.render_id}"endend
Every asset has a unique asset ID, the example below looks up an asset by its asset ID.
require"shotstack"Shotstack.configuredo |config|config.api_key['x-api-key']="H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD"config.host="api.shotstack.io"config.base_path="serve/stage"endid="ed43eae3-4825-4c03-979d-f7dc47b9997c"api_client=Shotstack::ServeApi.newbeginasset=api_client.get_asset(id).datarescue=>errorabort("Request failed:#{error.message}")endcaseasset.attributes.statuswhen"failed"puts">> Something went wrong, asset could not be copied."elseputs"Status:#{asset.attributes.status}"puts">> Asset CDN URL:#{asset.attributes.url}"puts">> Asset ID:#{asset.attributes.id}"puts">> Render ID:#{asset.attributes.render_id}"end
The following schemas are returned by requests to the Serve API.
TheAssetResponse is the response returned by the Serve APIget asset request. Includes details of a hosted video, image, audio file, thumbnail or poster image. The response follows thejson:api specification.
| Argument | Type | Description | Required |
|---|---|---|---|
| data | Shotstack::AssetResponseData | Returns an asset resource. | - |
TheAssetRenderResponse is the response returned by the Serve APIget asset by render id request. The response is an array of asset resources, including video, image, audio, thumbnail and poster image. The response follows thejson:api specification.
| Argument | Type | Description | Required |
|---|---|---|---|
| data | Shotstack::AssetResponseData[] | Returns an array of asset resources grouped by render id. | - |
TheAssetResponseData contains the type of resource (an asset) and attributes of the asset.
| Argument | Type | Description | Required |
|---|---|---|---|
| type | string | The type of resource, in this case it is anasset. | - |
| attributes | Shotstack::AssetResponseAttributes | The asset attributes including render id, url, filename, file size, etc... | - |
TheAssetResponseAttributes contains the list of asset attributes and their values.
| Argument | Type | Description | Required |
|---|---|---|---|
| id | string | The unique id of the hosted asset in UUID format. | - |
| owner | string | The owner id of the render task. | - |
| region | string | The region the asset is hosted, currently onlyau (Australia). | - |
| render_id | string | The original render id that created the asset in UUID format. Multiple asset can share the same render id. | - |
| filename | string | The asset file name. | - |
| url | string | The asset file name. | - |
| status | string | The status of the asset.
| - |
| created | string | The time the asset was created. | - |
| updated | string | The time the asset status was last updated. | - |
About
Ruby SDK for Shotstack, the cloud video editing API.