Making videos of the night sky with Stellarium

Automating Stellarium

Stellarium [1] is an open source astronomy software for rendering the night sky. This article provides a script that can automate the process of creating videos of the night sky with this software.

Stellarium has a powerfull built-in automation interface based on JavaScript (QtScript). This interface allows setting up and controlling almost all of it's parameters. As powerfull as the interface is, it does not allow you to create videos directly. To achieve this an additional layer on top of Stellarium is required. This layer is a Python script. The script is setting up a stellarium script for rendering the images and is then taking the frames rendered by Stellarium to create the video.

Sample of a video created via Stellariums remote API.

Download Project

First go to GitHub and download the kalstar project.


The script was developed on Linux. I consider it unlikely that it will run on a Non-Unix-like operating system such as Microsoft Windows without modifications. Before executing the script make sure you have the following software installed:

  • Stellarium
  • ffmpeg
  • VLC

Command Line Options

The program behaviour can be controlled with the following command line options.

Parameter Parameter Type Description
-long float Longitude of the observation loaction
-lat float Latitude of the observation loaction
-alt float Altitude of the center of the field of view
-az float Azimut in degrees (View direction)
-d date
(ISO 8601)
The simulation date. The animation automatically starts an hour after sunset on the specified day.
-fov float The field of viewin degrees.
-fps int Frame rate of the output video.
-t string The title of the video. The video title will be superimposed onto the video.
-ts float The simulation time span in hours.
-dt float The time difference between two sucessive frames in seconds.
-o string The name of the output video file.
-s - When this flag is specified an instance of VLC will be started once the video is created.


The following command will compute the first 2 hours of night sky in Berlin (Germany) on the 25th September of the year 2018.

python3 -lat 52.5186 -long 13.4083 -t "Look at all the Stars!" \
                   -az 90 -alt 25 -d 2018-09-25 -ts 2 -s -o out.mp4 -fov 70 -dt 30

How it works

The script explained here will create a script for the Stellarium scripting engine. It will then start Stellarium and execute this script causing it to create the animation frames. Once Stellarium is finished the python script will use ffmpeg to create a movie out of the frames.

The Stellarium Script

If you do not care about the details and inner workings of Stellarium scripting you can safely skip this section. You do not need the information provided here to use the python script.

If you do not care about the automated creation of videos just drop the following script into your local stellarium folder (~/.stellarium/scripts). You can then execute it from the script menu of Stellarium or start it by using the "--startup-script" option.

// Author: Ingo Berg
// Version: 1.0
// License: Public Domain
// Name: Kaleidoskop Sternenhimmel
// Description: Berechnung des Sternenhimmels

param_az = 90
param_alt = 25
param_lat = 50.911944
param_long = 13.34277
param_title = "Look at all the Stars!"
param_date = "2018-09-25T18:02:22"
param_timespan = 2.0
param_fov = 70
function makeVideo(date, file_prefix, caption, hours, long, lat, alt, azi)
    core.setDate(date, "utc");
    core.setObserverLocation(long, lat, 425, 1, "Freiberg", "Earth");

    core.moveToAltAzi(alt, azi)

    label = LabelMgr.labelScreen(caption, 70, 40, false, 40, "#aa0000");
    LabelMgr.setLabelShow(label, true);

    labelTime = LabelMgr.labelScreen("", 70, 90, false, 25, "#aa0000");
    LabelMgr.setLabelShow(labelTime, true);


    max_sec = hours * 60 * 60
    for (var sec = 0; sec < max_sec; sec += param_dt) {
        core.setDate('+' + param_dt + ' seconds');
        LabelMgr.setLabelText(labelTime, core.getDate(""));







StelMovementMgr.zoomTo(param_fov, 0);

makeVideo(param_date, "frame_", param_title, param_timespan, param_long, param_lat, param_alt, param_az)

The behaviour is controlled by the parameters at the top of the script:

Parameter Description
param_lat The latitude of the observation location
param_long The longitude of the observation location
param_title The title of the animation
param_date The day and time of the simulation. Must be in the format: "2018-09-25T18:02:22"
param_timespan The total time span of the simulation in hours
param_fov The field of view in degrees
param_dt Simulated time difference between two successive frames in seconds

References and Acknowledgements

The computation of sunset times in my code is done with routines written by Michel J. Anders This code would not have possible without the amazing work of the Team behind Stellarium as well as the people behind ffmpeg.

  1. "Stellarium Astronomy Software", Home Page of Stellarium
  2. "Start Small: Calulating sunrise and sunset in Python", Blog, Michel J. Anders