Skip to content

Commit 6eb718f

Browse files
jeffskijeffski
authored
Merge pull request #20 from shotstack/template-docs
Add templates to README
2 parents 284a7d6 + dc99454 commit 6eb718f

File tree

1 file changed

+263
-2
lines changed

1 file changed

+263
-2
lines changed

‎README.md‎

Lines changed: 263 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ For examples of how to use the SDK to create videos using code checkout the Node
1616
- [Video Editing](#video-editing)
1717
- [Video Editing Example](#video-editing-example)
1818
- [Status Check Example](#status-check-example)
19+
- [Save a Template Example](#save-a-template-example)
20+
- [Render a Template Example](#render-a-template-example)
1921
- [Video Editing Schemas](#video-editing-schemas)
2022
- [Edit](#edit)
2123
- [Timeline](#timeline)
@@ -37,6 +39,9 @@ For examples of how to use the SDK to create videos using code checkout the Node
3739
- [SkewTransformation](#skewtransformation)
3840
- [FlipTransformation](#fliptransformation)
3941
- [MergeField](#mergefield)
42+
- [Template Schemas](#template-schemas)
43+
- [Template](#template)
44+
- [TemplateRender](#templaterender)
4045
- [Output Schemas](#output-schemas)
4146
- [Output](#output)
4247
- [Size](#size)
@@ -54,6 +59,14 @@ For examples of how to use the SDK to create videos using code checkout the Node
5459
- [QueuedResponseData](#queuedresponsedata)
5560
- [RenderResponse](#renderresponse)
5661
- [RenderResponseData](#renderresponsedata)
62+
- [Template Response Schemas](#template-response-schemas)
63+
- [TemplateResponse](#templateresponse)
64+
- [TemplateResponseData](#templateresponsedata)
65+
- [TemplateDataResponse](#templatedataresponse)
66+
- [TemplateDataResponseData](#templatedataresponsedata)
67+
- [TemplateListResponse](#templatelistresponse)
68+
- [TemplateListResponseData](#templatelistresponsedata)
69+
- [TemplateListResponseItem](#templatelistresponseitem)
5770
- [Inspecting Media](#inspecting-media)
5871
- [Probe Example](#probe-example)
5972
- [Probe Schemas](#probe-schemas)
@@ -143,7 +156,7 @@ DeveloperKey.apiKey = 'H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD'; // use the cor
143156

144157
const api = new Shotstack.EditApi();
145158

146-
const id = "75143ec6-4b72-46f8-a67a-fd7284546935"; // use the render id from previous example
159+
const id = '75143ec6-4b72-46f8-a67a-fd7284546935'; // use the render id from previous example
147160

148161
api.getRender(id, { data: false, merged: true }).then((data) => {
149162
if (data.response.status === 'done') {
@@ -152,6 +165,111 @@ api.getRender(id, { data: false, merged: true }).then((data) => {
152165
});
153166
```
154167

168+
### Save a Template Example
169+
170+
The example below uses the Edit we create in the [Video Editing Example](#video-editing-example) and saves it as a
171+
template. The template can be rendered at a later date and can include placeholders. Placeholders can be replaced
172+
when rendered using [merge fields](#mergefield).
173+
174+
This example uses a placeholder for the video src (URL), trim (TRIM), and length (LENGTH) to allow you to trim any video
175+
using a template.
176+
177+
```javascript
178+
const Shotstack = require('shotstack-sdk');
179+
180+
const defaultClient = Shotstack.ApiClient.instance;
181+
defaultClient.basePath = 'https://api.shotstack.io/stage';
182+
183+
const DeveloperKey = defaultClient.authentications['DeveloperKey'];
184+
DeveloperKey.apiKey = 'H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD'; // use the correct API key
185+
186+
const api = new Shotstack.EditApi();
187+
188+
let videoAsset = new Shotstack.VideoAsset;
189+
videoAsset
190+
.setSrc('{{ URL }}')
191+
.setTrim('{{ TRIM }}');
192+
193+
let videoClip = new Shotstack.Clip;
194+
videoClip
195+
.setAsset(videoAsset)
196+
.setStart(0)
197+
.setLength('{{ LENGTH }}');
198+
199+
let track = new Shotstack.Track;
200+
track.setClips([videoClip]);
201+
202+
let timeline = new Shotstack.Timeline;
203+
timeline.setTracks([track]);
204+
205+
let output = new Shotstack.Output;
206+
output
207+
.setFormat('mp4')
208+
.setResolution('sd');
209+
210+
let edit = new Shotstack.Edit;
211+
edit
212+
.setTimeline(timeline)
213+
.setOutput(output);
214+
215+
const template = new Shotstack.Template;
216+
template
217+
.setName('Trim Template')
218+
.setTemplate(edit);
219+
220+
api.postTemplate(template).then((data) => {
221+
console.log(data.response.id);
222+
});
223+
```
224+
225+
### Render a Template Example
226+
227+
The example below renders the template we created in the previous example and includes merge fields that will replace
228+
the placeholders. Once submitted use the returned render ID and call the [Status Check Example](#status-check-example)
229+
to get the render progress.
230+
231+
```javascript
232+
const Shotstack = require('shotstack-sdk');
233+
234+
const defaultClient = Shotstack.ApiClient.instance;
235+
defaultClient.basePath = 'https://api.shotstack.io/stage';
236+
237+
const DeveloperKey = defaultClient.authentications['DeveloperKey'];
238+
DeveloperKey.apiKey = 'H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD'; // use the correct API key
239+
240+
const api = new Shotstack.EditApi();
241+
242+
const id = '8aeabb0e-b5eb-8c5e-847d-82297dd4802a'; // use the template id from previous example
243+
244+
const mergeFieldUrl = new Shotstack.MergeField;
245+
mergeFieldUrl
246+
.setFind('URL')
247+
.setReplace('https://s3-ap-southeast-2.amazonaws.com/shotstack-assets/footage/skater.hd.mp4');
248+
249+
const mergeFieldTrim = new Shotstack.MergeField;
250+
mergeFieldTrim
251+
.setFind('TRIM')
252+
.setReplace(3);
253+
254+
const mergeFieldLength = new Shotstack.MergeField;
255+
mergeFieldLength
256+
.setFind('LENGTH')
257+
.setReplace(6);
258+
259+
const template = new Shotstack.TemplateRender;
260+
template
261+
.setId(id)
262+
.setMerge([
263+
mergeFieldUrl,
264+
mergeFieldTrim,
265+
mergeFieldLength,
266+
]);
267+
268+
api.postTemplateRender(template).then((data) => {
269+
console.log(data.response.id);
270+
});
271+
```
272+
155273
## Video Editing Schemas
156274

157275
The following schemas are used to prepare a video edit.
@@ -170,7 +288,7 @@ edit
170288
.setTimeline(timeline)
171289
.setOutput(output)
172290
.setMerge(merge)
173-
.setCallback("https://my-server.com/callback.php")
291+
.setCallback('https://my-server.com/callback.php')
174292
.setDisk("local");
175293
```
176294

@@ -700,6 +818,57 @@ setReplace(replace) | The replacement value. The replacement can be any valid JS
700818
701819
---
702820
821+
## Template Schemas
822+
823+
The following schemas specify how to use templates to store and render templates. A template lets you save an
824+
[Edit](#edit) that can be rendered by its template ID and optionally include merge fields that are merged with the
825+
template when rendered.
826+
827+
### Template
828+
829+
A template is a saved [Edit](#edit) than can be loaded and re-used.
830+
831+
#### Example:
832+
833+
```javascript
834+
const Shotstack = require('shotstack-sdk');
835+
836+
const template = new Shotstack.Template;
837+
template
838+
.setName('My Template')
839+
.setTemplate(edit);
840+
```
841+
842+
#### Methods:
843+
844+
Method | Description | Required
845+
:--- | :--- | :---:
846+
setName(string name) | The template name. | Y
847+
setTemplate([Shotstack.Edit](#edit) edit)) | An edit defines the arrangement of a video on a timeline, an audio edit or an image design and the output format. | Y
848+
849+
### TemplateRender
850+
851+
Configure the id and optional merge fields to render a template by id.
852+
853+
#### Example:
854+
855+
```javascript
856+
const Shotstack = require('shotstack-sdk');
857+
858+
const template = new Shotstack.TemplateRender;
859+
template
860+
.setId('21e781c0-8232-4418-fec1-cc99f0280c21')
861+
.setMerge(merge);
862+
```
863+
864+
#### Methods:
865+
866+
Method | Description | Required
867+
:--- | :--- | :---:
868+
setId(string id) | The id of the template to render in UUID format. | Y
869+
setMerge([Shotstack.MergeField[]](#mergefield) 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 value `Jane`. | -
870+
871+
---
703872
## Output Schemas
704873
705874
The following schemas specify the output format and settings.
@@ -1029,6 +1198,98 @@ getData(): [Shotstack.Edit](#edit) | The timeline and output data to be rendered
10291198
getCreated(): string | The time the render task was initially queued. | Y
10301199
getUpdated(): string | The time the render status was last updated. | Y
10311200
1201+
---
1202+
1203+
## Template Response Schemas
1204+
1205+
The following schemas are returned by the templates endpoint, including create, update and rendering a template.
1206+
1207+
### TemplateResponse
1208+
1209+
The response received after a [template](#create-template) is submitted. The template is saved and a unique
1210+
template id is returned.
1211+
1212+
#### Methods:
1213+
1214+
Method | Description | Required
1215+
:--- | :--- | :---:
1216+
getSuccess(): bool | `true` if successfully queued, else `false`. | Y
1217+
getMessage(): string | `Created`, `Bad Request` or an error message. | Y
1218+
getResponse(): [Shotstack.TemplateResponseData](#templateresponsedata) | `TemplateResponseData` or an error message. | Y
1219+
1220+
### TemplateResponseData
1221+
1222+
The response data returned with the [Shotstack.TemplateResponse](#templateresponse).
1223+
1224+
#### Methods:
1225+
1226+
Method | Description | Required
1227+
:--- | :--- | :---:
1228+
getMessage(): string | Success response message or error details. | Y
1229+
getId(): string | The unique id of the template in UUID format. | Y
1230+
1231+
### TemplateDataResponse
1232+
1233+
The template data including the template name and [Edit](#edit).
1234+
1235+
#### Methods:
1236+
1237+
Method | Description | Required
1238+
:--- | :--- | :---:
1239+
getSuccess(): bool | `true` if successfully queued, else `false`. | Y
1240+
getMessage(): string | `Created`, `Bad Request` or an error message. | Y
1241+
getResponse(): [Shotstack.TemplateDataResponseData](#templatedataresponsedata) | `TemplateDataResponseData` or an error message. | Y
1242+
1243+
### TemplateDataResponseData
1244+
1245+
The response data returned with the [TemplateDataResponse](#templatedataresponse).
1246+
1247+
#### Methods:
1248+
1249+
Method | Description | Required
1250+
:--- | :--- | :---:
1251+
getId(): string | The unique id of the template in UUID format. | Y
1252+
getName(): string | The template name. | Y
1253+
getOwner(): string | The owner id of the templates. | Y
1254+
getTemplate(): [Shotstack.Edit](#edit) | `Edit` or an error message. | Y
1255+
1256+
### TemplateListResponse
1257+
1258+
A list of previously saved templates.
1259+
1260+
#### Methods:
1261+
1262+
Method | Description | Required
1263+
:--- | :--- | :---:
1264+
getSuccess(): bool | `true` if successfully queued, else `false`. | Y
1265+
getMessage(): string | `Created`, `Bad Request` or an error message. | Y
1266+
getResponse(): [Shotstack.TemplateListResponseData](#templatelistresponsedata) | `TemplateListResponseData` or an error message. | Y
1267+
1268+
### TemplateListResponseData
1269+
1270+
The response data returned with the [TemplateListResponse](#templatelistresponse).
1271+
1272+
#### Methods:
1273+
1274+
Method | Description | Required
1275+
:--- | :--- | :---:
1276+
getOwner(): bool | The owner id of the templates. | Y
1277+
getTemplates(): [[Shotstack.TemplateListResponseItem]](#templatelistresponseitem) | The list of templates. | Y
1278+
1279+
### TemplateListResponseItem
1280+
1281+
The individual template item returned with the [TemplateListResponseData](#templatelistresponsedata) templates
1282+
list.
1283+
1284+
#### Methods:
1285+
1286+
Method | Description | Required
1287+
:--- | :--- | :---:
1288+
getId(): string | The unique id of the template in UUID format. | Y
1289+
getName(): string | The template name | Y
1290+
getCreated(): string | The time the template was created. | -
1291+
getUpdated(): string | The time the template was last updated. | -
1292+
10321293
---
10331294
## Inspecting Media
10341295

0 commit comments

Comments
 (0)