Movies

The movie APIs can be used to generate custom videos of up to three image datasource layers composited together. Solar feature/event markers pins, extended region polygons, associated text labels, and a size-of-earth scale indicator can optionally be overlayed onto a movie.

Movie generation is performed asynchronously due to the amount of resources required to complete each video. Movie requests are queued and then processed (in the order in which they are received) by one of several worker processes operating in parallel.

As a user of the API, begin by sending a ‘queueMovie’ request. If your request is successfully added to the queue, you will receive a response containing a unique movie identifier. This identifier can be used to monitor the status of your movie via ‘getMovieStatus’ and then download or play it (via ‘downloadMovie’ or ‘playMovie’) once its status marked as completed.

Movies may contain between 10 and 300 frames. The movie frames are chosen by matching the closest image available at each step within the specified range of dates, and are automatically selected by the API. The region to be included in the movie may be specified using either the top-left and bottom-right coordinates in arc-seconds, or a center point in arc-seconds and a width and height in pixels. See the Coordinates Appendix for more infomration about working with the coordinates used by Helioviewer.org.

queueMovie

GET /v2/queueMovie/

Create a custom movie by submitting a request to the movie generation queue. The response returned will provide you with a unique Movie ID that can be used to check on the status of your movie (via getMovieStatus) and to download your movie (via downloadMovie).

Request Parameters:

Parameter

Required

Type

Example

Description

startTime

Required

string

2010-03-01T12:12:12Z

Desired date and time of the first frame of the movie. ISO 8601 combined UTC date and time UTC format.

endTime

Required

string

2010-03-04T12:12:12Z

Desired date and time of the final frame of the movie. ISO 8601 combined UTC date and time UTC format.

layers

Required

string

[3,1,100],[4,1,100]
or
[3,1,100,2,60,1,2010-03-01T12:12:12.000Z]

Image datasource layer(s) to include in the movie.

events

Required

string

[AR,HMI_HARP;SPoCA,1],[CH,all,1]

List feature/event types and FRMs to use to annoate the movie. Use the empty string to indicate that no feature/event annotations should be shown.

eventsLabels

Required

boolean

false

Optionally annotate each event marker with a text label.

imageScale

Required

number

21.04

Image scale in arcseconds per pixel.

format

Optional

string

mp4

Movie format (mp4, webm, flv). Default value is mp4.

frameRate

Optional

string

15

Movie frames per second. 15 frames per second by default.

maxFrames

Optional

string

300

Maximum number of frames in the movie. May be capped by the server.

scale

Optional

boolean

false

Optionally overlay an image scale indicator.

scaleType

Optional

string

earth

Image scale indicator.

scaleX

Optional

number

-1000

Horizontal offset of the image scale indicator in arcseconds with respect to the center of the Sun.

scaleY

Optional

number

-500

Vertical offset of the image scale indicator in arcseconds with respect to the center of the Sun.

movieLength

Optional

number

4.3333

Movie length in seconds.

watermark

Optional

boolean

true

Optionally overlay a Helioviewer.org watermark image. Enabled by default.

width

Optional

string

1920

Width of the field of view in pixels. (Used in conjunction width x0,`y0`, and height).

height

Optional

string

1200

Height of the field of view in pixels. (Used in conjunction width x0,`y0`, and width).

x0

Optional

string

0

The horizontal offset of the center of the field of view from the center of the Sun. Used in conjunction with y0, width, and height.

y0

Optional

string

0

The vertical offset of the center of the field of view from the center of the Sun. Used in conjunction with x0, width, and height.

x1

Optional

string

-5000

The horizontal offset of the top-left corner of the field of view with respect to the center of the Sun (in arcseconds). Used in conjunction with y1, x2, and y2.

y1

Optional

string

-5000

The vertical offset of the top-left corner of the field of view with respect to the center of the Sun (in arcseconds). Used in conjunction with x1, x2, and y2.

x2

Optional

string

5000

The horizontal offset of the bottom-right corner of the field of view with respect to the center of the Sun (in arcseconds). Used in conjunction with x1, y1, and y2.

y2

Optional

string

5000

The vertical offset of the bottom-right corner of the field of view with respect to the center of the Sun (in arcseconds). Used in conjunction with x1, y1, and x2.

callback

Optional

string

Wrap the response object in a function call of your choosing.

size

Optional

number

0

Scale video to preset size:
0 - Original size
1 - 720p (1280 x 720, HD Ready);
2 - 1080p (1920 x 1080, Full HD);
3 - 1440p (2560 x 1440, Quad HD);
4 - 2160p (3840 x 2160, 4K or Ultra HD).

movieIcons

Optional

number

0

Display other user generated movies on the video.

followViewport

Optional

number

0

Rotate field of view of movie with Sun.

reqObservationDate

Optional

string

2017-08-30T14:45:53.000Z

Viewport time. Used when ‘followViewport’ enabled to shift viewport area to correct coordinates.

Example: Queued Movie (JSON)

JSON response to “queueMovie” and “reQueueMovie” API requests.

Example Request:
https://api.helioviewer.org/v2/queueMovie/?startTime=2010-03-01T12:12:12Z&endTime=2010-03-04T12:12:12Z&layers=[3,1,100],[4,1,100]&events=[AR,HMI_HARP;SPoCA,1],[CH,all,1]&eventsLabels=false&imageScale=21.04&x1=-5000&y1=-5000&x2=5000&y2=5000
Example Response:
{
  "id": "z6vX5",
  "eta": 376,
  "queue": 0,
  "token": "50e0d98f645b42d159ec1c8a1e15de3e"
}
Response Description

Parameter

Required

Type

Description

eta

Required

number

Estimated time until movie generation will be completed in seconds

id

Required

string

Unique movie identifier (e.g. “z6vX5”)

queue

Required

number

Position in movie generation queue

token

Required

string

reQueueMovie

GET /v2/reQueueMovie/

Re-generate a custom movie that is no longer cached on disk. Once the movie has been successfully queued for regeneration, the Movie ID can be used to check on the status of the movie (via getMovieStatus) and to download the movie (via downloadMovie).

Request Parameters:

Parameter

Required

Type

Example

Description

id

Required

string

VXvX5

Unique movie identifier (provided by the response to a queueMovie request).

Example: Queued Movie (JSON)

JSON response to queueMovie and reQueueMovie API requests.

Example Request:
https://api.helioviewer.org/v2/reQueueMovie/?id=VXvX5
Example Response:
{
    "id": "VXvX5",
    "eta": 285,
    "queue": 0,
    "token": "4673d6db4e2a3365ab361267f2a9a112"
}
Response Description

Parameter

Required

Type

Description

eta

Required

number

Estimated time until movie generation will be completed in seconds

id

Required

string

Unique movie identifier (e.g. “z6vX5”)

queue

Required

number

Position in movie generation queue

token

Required

string

getMovieStatus

GET /v2/getMovieStatus/

Request Parameters:

Parameter

Required

Type

Example

Description

id

Required

string

VXvX5

Unique movie identifier (provided by the response to a queueMovie request).

format

Required

string

mp4

Movie format (mp4, webm, or flv).

verbose

Optional

boolean

true

Optionally include extra metadata in the response.

callback

Optional

string

Wrap the response object in a function call of your choosing.

token

Optional

string

Example: Movie Status (JSON)

A JSON object containing metadata describing a user-generated movie, including its generation status (0=queued, 1=processing, 2=finished, 3=invalid).

Example Request:
https://api.helioviewer.org/v2/getMovieStatus/?id=VXvX5&format=mp4
Example Response:
{
  "frameRate": 15,
  "numFrames": 300,
  "startDate": "2014-02-03 20:26:16",
  "status": 2,
  "endDate": "2014-02-05 20:16:40",
  "width": 846,
  "height": 820,
  "title": "SDO AIA AIA 1600 (2014-02-03 20:26:16 - 20:16:40 UTC)",
  "thumbnails": {
    "icon": "http://api.helioviewer.org/cache/movies/2014/02/05/VXvX5/preview-icon.png",
    "small": "http://api.helioviewer.org/cache/movies/2014/02/05/VXvX5/preview-small.png",
    "medium": "http://api.helioviewer.org/cache/movies/2014/02/05/VXvX5/preview-medium.png",
    "large": "http://api.helioviewer.org/cache/movies/2014/02/05/VXvX5/preview-large.png",
    "full": "http://api.helioviewer.org/cache/movies/2014/02/05/VXvX5/preview-full.png"
  },
  "url": "http://api.helioviewer.org/cache/movies/2014/02/05/VXvX5/2014_02_03_20_26_16_2014_02_05_20_16_40_.mp4",
  "statusLabel": "Completed"
}
Response Description

Parameter

Required

Type

Description

status

Required

number

Movie generation status
(0=queued, 1=processing, 2=finished, 3=invalid)

Example: Movie Status Verbose (JSON)

A JSON object containing metadata describing a user-generated movie, including its generation status (0=queued, 1=processing, 2=finished, 3=invalid) and the parameters used to create it.

Example Request:
https://api.helioviewer.org/v2/getMovieStatus/?id=VXvX5&format=webm&verbose=true&callback=callbackTest
Example Response:
callbackTest({
  "frameRate": 15,
  "numFrames": 300,
  "startDate": "2014-02-03 20:26:16",
  "status": 2,
  "endDate": "2014-02-05 20:16:40",
  "width": 846,
  "height": 820,
  "title": "SDO AIA AIA 1600 (2014-02-03 20:26:16 - 20:16:40 UTC)",
  "thumbnails": {
    "icon": "http://api.helioviewer.org/cache/movies/2014/02/05/VXvX5/preview-icon.png",
    "small": "http://api.helioviewer.org/cache/movies/2014/02/05/VXvX5/preview-small.png",
    "medium": "http://api.helioviewer.org/cache/movies/2014/02/05/VXvX5/preview-medium.png",
    "large": "http://api.helioviewer.org/cache/movies/2014/02/05/VXvX5/preview-large.png",
    "full": "http://api.helioviewer.org/cache/movies/2014/02/05/VXvX5/preview-full.png"
  },
  "url": "http://api.helioviewer.org/cache/movies/2014/02/05/VXvX5/2014_02_03_20_26_16_2014_02_05_20_16_40_.webm",
  "timestamp": "2014-02-05 20:25:55",
  "duration": 20,
  "imageScale": 2.42044,
  "layers": "[SDO,AIA,AIA,1600,1,100]",
  "events": "[AR,all,1],[CC,all,1],[CD,all,1],[CH,all,1],[CJ,all,1],[CE,all,1],[CR,all,1],[CW,all,1],[EF,all,1],[ER,all,1],[FI,all,1],[FA,all,1],[FE,all,1],[FL,all,1],[LP,all,1],[OS,all,1],[PG,all,1],[SG,all,1],[SP,all,1],[SS,all,1]",
  "x1": -1011.7442962,
  "y1": -980.2785645,
  "x2": 1035.9487052,
  "y2": 1004.4829735,
  "statusLabel": "Completed"
})
Response Description

Parameter

Required

Type

Description

endDate

Optional

string

Date of final frame in movie (e.g. “2014-02-05 19:40:16”)

frameRate

Optional

number

Number of frames per second (e.g. 15)

height

Optional

number

Pixel height of movie

numFrames

Optional

number

Total number of frames (e.g. 300)

startDate

Optional

string

Date of first frame in movie (e.g. “2014-02-05 19:40:16”)

status

Required

number

Movie generation status (0=queued, 1=processing, 2=finished, 3=invalid)

title

Optional

string

Title of movie (e.g. “SDO AIA 1600 (2014-02-03 20:26:16 - 19:40:16 UTC)”)

url

Optional

string

Download URL for movie in specified format

width

Optional

number

Pixel width of movie

duration

Optional

string

Movie duration in seconds (e.g. 20)

events imageScale

Optional Optional

string number

Solar Feature/Event layer(s) contained in movie Image scale in arcseconds per pixel (e.g. 2.42044)

layers

Optional

string

Image datasource layer(s) contained in movie

timestamp

Optional

string

Timestamp (e.g. “2014-02-05 20:25:55”)

x1

Optional

number

Arc seconds from Sun center (e.g. -1011.7442962)

y1

Optional

number

Arc seconds from Sun center (e.g. -980.2785645)

x2

Optional

number

Arc seconds from Sun center (e.g. 1035.9487052)

y2

Optional

number

Arc seconds from Sun center (e.g. 1004.4829735)

downloadMovie

GET /v2/downloadMovie/

Download a custom movie in one of three file formats.

Request Parameters:

Parameter

Required

Type

Example

Description

id

Required

string

VXvX5

Unique movie identifier (provided by the response to a queueMovie request).

format

Required

string

mp4

Movie Format (mp4, webm, or flv).

hq

Optional

boolean

true

Optionally download a higher-quality movie file (valid for .mp4 movies only, ignored otherwise).

Example: binary (movie data)

Example Request:
https://api.helioviewer.org/v2/downloadMovie/?id=VXvX5&format=mp4

playMovie

GET /v2/playMovie/

Output an HTML web page with the requested movie embedded within.

Request Parameters:

Parameter

Required

Type

Example

Description

id

Required

string

VXvX5

Unique movie identifier (provided by the response to a queueMovie request).

format

Required

string

mp4

Movie format (mp4, webm, or flv).

hq

Optional

boolean

true

Optionally download a higher-quality movie file (valid for .mp4 movies only, ignored otherwise).

width

Optional

number

846

Width of embedded movie player in pixels. Defaults to the actual width of the movie itself.

height

Required

string

820

Height of embedded movie player in pixels. Defaults to the actual height of the movie itself.

Example: string (HTML)

Example Request:
https://api.helioviewer.org/v2/playMovie/?id=VXvX5&format=mp4&hq=true
Example Response:
<!DOCTYPE html>
<html>
<head>
    <title>Helioviewer.org - 2014_02_03_20_26_16_2014_02_05_20_16_40_AIA_1600-hq.mp4</title>
    <script src="http://helioviewer.org/lib/flowplayer/flowplayer-3.2.8.min.js"></script>
</head>
<body>
    <!-- Movie player -->
    <div href="http://helioviewer.org/cache/movies/2014/02/05/VXvX5/2014_02_03_20_26_16_2014_02_05_20_16_40_AIA_1600-hq.mp4"
       style="display:block; width: 846px; height: 820px;"
       id="movie-player">
    </div>
    <br>
    <script language="javascript">
        flowplayer("movie-player", "http://helioviewer.org/lib/flowplayer/flowplayer-3.2.8.swf", {
            clip: {
                autoBuffering: true,
                scaling: "fit"
            }
        });
    </script>
</body>
</html>