Batch Server API

Overview

The batch server is started automatically when you run a batch.

However you can also start it manually. This is required when you want to run the batches over a network.

To create a batch server that you can connect to copy the Render+ folder to the server PC and then run the start server for the operating system you are using. Linux, Mac and Windows are supported.

If you are using one of the *BSD, like FreeBSD there’s a good chance the Linux script will also work for you.

You can also run the R+ server on more than one machine and have it distribute the render jobs over all the available machines.

The servers that only do rendering are called “Workers”, while the ones that coordinate are called “Mains”. You don’t set the server itself to be a worker or a main, the difference comes from how they are used.

Let’s say you have the following:

• Server A

• Server B

• Server C

If you set Server B and Server C as workers in the configuration file for Server A, these two will be the workers and server A will be the main.

A will interact directly with the addon, while B and C receive render jobs from A.

You can find more information on the configuration file below.

Server command line arguments

You can pass several arguments to the batch server when running from the command line.

Property	Description
–port	Port to listen for clients
–no-cleanup	Don’t clean the temp folder after running batch
–write-log	Path to write the server’s log file
–version	Print version and quit
–config	Load a configuration file

The default for –port is 7777 (same as the default in the addon’s preferences). Everything else is empty by default.

Server config file

The batch server’s configuration file is a TOML file that can be placed anywhere. To use a configuraiton file pass the –config argument to the start server script.

The configuration consists of one main section and zero or more worker sections.

Property	Description
port	Port to listen for clients
cleanup	Clean the temp folder after running batch
log_path	Path to write the server’s log file
disable_workers	Don’t use works and run renders locally
blender	Path to blender executable to use for rendering

The “blender” setting should be a full, absolute path to a blender binary (.exe in Windows for example). If this setting is present, it will be used instead of the blender binary set in the addon preferences. Likewise if the addon preferences don’t have a blender binary set, this will be used instead.

Worker sections should be named “workers.[NAME]”, where name is a a custom name for that worker.

Property		Description
port		Port to listen for the main server
address | IP adress or hostname to connect to this worker
poll_interval | Interval rate in seconds to poll the server for information

Full example:

[main]
port = 7777
cleanup = false
log_path = "./renderplus.log"
disable_workers = false

[workers.station1]
address = "server-worker_1"
port = 7777
poll_interval = 2.0

[workers.station2]
address = "server-worker_2"
port = 7777
poll_interval = 2.0

Batch Server API

The batch server exposes a REST API that is used by the addon. You can also use this API to control the server manually, or integrate it into your own software.

Routes

Route	Method	Description
/batch/recipe	POST	Submit a batch recipe
/batch/file	POST	Upload a blendfile
/batch/start	GET	Start the batch
/test	GET	Get batch server information
/batch	GET	Query the batch status
/batch/ready	GET	Determine if the server can run a batch
/batch	DELETE	Cancel the current batch
/batch/name	GET	Query the batch’s name (blend file)
/batch/jobs/{id}	GET	Query the status of a specific render job
/batch/jobs/current	DELETE	Cancel the render job currently running

Starting a Batch

Before starting a batch we need to submit a recipe. This can be done by sending a POST request to http://localhost:[PORT]/batch/recipe.

The data sent to start a batch is called a recipe and is a dictionary with a specific set of keys. Check out the sample below. You can see how Render+ generates these by looking at the contents of the recipe module. Look for the recipe.py file inside the batch folder.

The data should be a JSON dictionary, and Content-type should be set to application/json.

Recipe sample

Here’s a sample of a Batch recipe with 1 render job. Note that jobs is a list of dictionaries.

{
  "name": "/home/user/batch.blend",
  "version": 2.2,
  "settings": {
    "rss": {
      "enabled": false,
      "path": "/home/user/feed.rss"
    },
    "global_percentage": {
      "enabled": false,
      "value": 100
    },
    "global_size": {
      "enabled": false,
      "value": [1920, 1080]
    },
    "write_log": false,
    "ignore_border": false
  },
  "blender_bin": "/bin/blender",
  "hooks": {
    "PRE_BATCH": [],
    "POST_BATCH": []
  },
  "poweroff": {
    "enabled": false,
    "action": "DISABLED"
  },
  "notifications": {
    "desktop": false,
    "sound": {
      "enabled": false,
      "file": "/home/user/.config/blender/2.80/scripts/addons/renderplus/assets/notification.ogg",
      "volume": 10
    },
    "mail": {
      "enabled": false,
      "user": "some@somemail.com",
      "pass": "password",
      "ssl": true,
      "to": "my@real-mail.com",
      "server": "smtp.mail.com"
    }
  },
  "jobs": [
    {
      "enabled": true,
      "id": 0,
      "name": "Some job",
      "output": "/home/user/render_Untitled_Scene",
      "external": false,
      "layer": "",
      "blendfile": "blendname.blend",
      "filename": "/home/user/blendname.blend",
      "animated": false,
      "engine": "BLENDER_EEVEE",
      "threads": 0,
      "hooks": {
        "PRE_JOB": [
          {
            "enabled": false,
            "cmd": "echo 'pre_job'"
          }
        ],
        "POST_JOB": [
          {
            "enabled": false,
            "cmd": "echo 'post_job'"
          }
        ]
      },
      "size": [1920, 1080],
      "blend_file": "/home/user/batch.blend",
      "scene": "Scene",
      "camera": "Camera",
      "world": "World",
      "frame_still": 1,
      "frame_start": 1,
      "frame_end": 250,
      "format": "PNG",
      "section": {
        "enabled": false,
        "x": 0,
        "y": 0,
        "width": 1,
        "height": 1
      },
      "cycles": {
        "samples": 0,
        "device": "DEFAULT"
      },
      "custom_overrides": []
    },
  ]
}

Polling

To poll the batch’s status send a GET request to http://localhost:[PORT]/batch. The response will have a HTTP status code of 200 and contain a JSON dictionary. You can also request data for a single job only using http://localhost:[PORT]/batch/jobs/[ID]. Where ID is the number of the job in the list, starting from zero.

The batch’s name is available by requesting http://localhost:[PORT]/batch/name.

Poll Response example

{
  "status" : "RUNNING",
  "times" : {
    "started" : 1545401461.3625693,
    "finished" : null,
    "rendertime" : null
  },
  "stats" : {
    "slowest_index" : null,
    "slowest_time" : null,
    "fastest_index" : null,
    "fastest_time" : null,
    "average_time" : null
  },
  "messages" : [],
  "jobs" : [
    {
      "id" : 0,
      "status" : "RUNNING",
      "times" : {
        "started" : 1545401461.3666012,
        "finished" : null,
        "rendertime" : null
      },
      "messages" : [],
      "progress" : 9.765625,
      "engine" : {
        "type" : "BLENDER_EEVEE",
        "data" : {
          "frame" : "1",
          "mem" : "127.56M",
          "elapsed" : "00:00.42",
          "samples_done" : "25",
          "samples_todo" : "256"
        }
      }
    },
    {
      "id" : 1,
      "status" : "DISABLED",
      "times" : {
        "started" : null,
        "finished" : null,
        "rendertime" : null
      },
      "messages" : [],
      "progress" : 0,
      "engine" : {
        "type" : null,
        "data" : null
      }
    },
    {
      "id" : 2,
      "status" : "QUEUED",
      "times" : {
        "started" : null,
        "finished" : null,
        "rendertime" : null
      },
      "messages" : [],
      "progress" : 0,
      "engine" : {
        "type" : null,
        "data" : null
      }
    }
  ],
  "current_job" : 0
}

Fields

• status: Can be either WAITING, RUNNING, FINISHED or, CANCELLED. If a batch has been run the status will be either FINISHED or CANCELLED. If no batch has been run the status will be WAITING.

• current_job: ID of the renderjob currently being rendered

• messages: Usually empty. Sometimes used for error messages.

• times: Start, finish and render times for the whole batch. Finished and rendertime will be null while the batch is running.

• stats: Contains average rendertime, as well as fastest and slowest jobs. All these will be null while the batch is running or if the batch is cancelled.

• jobs: A list with the status of each job.

A render job has the following keys:

• id: The ID for the render job

• status: QUEUED, DISABLED, RUNNING, FINISHED or CANCELLED

• times: Start, finish and render times for the job

• messages: Usually empty. Used for error messages when the job fails

• progress: An integer in the rage 0…100 representing the progress of the render

• engine: A dictionary containing two items: Type (name of the render engine or NON_COMPATIBLE) and data with data pulled from the render engine’s stdout

Note that NON_COMPATIBLE doesn’t mean it won’t render, but only that Render+ doesn’t know how to get information from the engine. The data key can have different keys depending on the engine.

Errors

In case of errors the routes will return an error HTTP code and a dictionary with more information. Requesting for an invalid route will return a 404.

Route	Method	HTTP Code	Description
/batch	POST	406	Wrong content-type sent (must be JSON)
/batch	POST	409	Can’t start because a batch is already running
/batch	GET	409	Can’t poll because no batch has been run
/batch/jobs/{id }	GET	409	Can’t poll because no batch has been run
/batch/jobs/{id }	GET	400	Wrong or missing index of job to poll
/batch/name	GET	409	Can’t poll because no batch has been run
/batch	DELETE	409	Can’t cancel because no batch is running
/batch/jobs/cur rent	DELETE	409	Can’t cancel because no batch is running

Here’s an example of an error response:

{
  "status" : "Not running a batch right now",
}

When a job fails it doesn’t produce an error message. It’s status is set to FAILED.

Logs

Batch server logs are different from the addon’s logs, and they are only written if you use the --write-logs parameter when starting the server. They are written to the server/log folder. The server writes a new log file every time it is started. The filename format is renderplus_[day]-[month]-[year]-[hour]-[minute]-[seconds]

Stopping the server

To stop the server press CTRL+C while it’s running.

Listing GPUs

To find a list of GPUs available to Blender in your system and their numbers you can pass the --list-gpus setting to the server.

This parameter needs a path to the Blender binary you want to use for batch rendering.

▶ python3 server --list-gpus /usr/bin/Blender

Blender 2.90.0 (hash 0330d1af29c0 built 2020-08-31 11:54:54)
Read prefs: /home/januz/.config/blender/2.90/config/userpref.blend
found bundled python: /home/januz/down/blender-2.90.0-linux64/2.90/python

GPUS AVAILABLE FOR RENDERING
--------------------------------------------------------------------------------
Radeon RX Vega 56 | Number: 0

Blender quit