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	Handle to job in the movie builder queue

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).
force	Optional	bool	false	Forces rebuilding of a movie. Useful if new data has been added.

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		Handle to job in the movie builder queue.

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>