Dart Library for RICOH THETA live preview testing

We’re working on a new Dart and Flutter project to test the camera.getLivePreview API from the RICOH THETA V, Z1, and SC2 models.

Code on GitHub

GitHub - codetricity/tpreview: RICOH THETA Live Preview Tester

There is a command line tool that can be used for testing. The tool uses a library, or Dart package, that is stored in the same repo.

YouTube Tutorial on Using Package to Build Desktop and Mobile Apps

RICOH THETA Live Preview Tester

Command line tester for RICOH THETA get live preview API.

The tester can also be used to test a subset of common camera commands.


dart .\tpreview.dart
RICOH THETA Live Preview tester

Usage: tpreview <command> [arguments]

Global options:
-h, --help    Print this usage information.

Available commands:
  checkForIdle       wait for camera to be idle after startCapture or self timer for next command
  imageMode          Switch camera to image mode
  info               camera information, including model, serial number
  intervalShoot      test interval shooting with 2 sets of 2 shots
  listFiles          list video and image files on camera
  previewFormat      Set preview format
  printFrames        print frame bytes to console for testing
  saveFrames         save frames from live preview stream
  sc2SaveFrames      THETA SC2 save frames from live preview stream
  setOption          Set single camera option
  state              camera status, battery level, API version, last file URL
  takePicture        take single still image.  Camera must be in still image mode
  takePictureReady   take single still image and show when camera is ready for next command
  videoMode          Switch camera to video mode

Run "tpreview help <command>" for more information about a command.

Options for saveFrames

dart .\tpreview.dart saveFrames --help
save frames from live preview stream

Usage: tpreview saveFrames [arguments]
-h, --help      Print this usage information.
    --frames    --frames=5
    --delay     --delay=1000  : for 1000ms

Run "tpreview help" to see global options.

As the maximum frame rate is 30fps, the lowest delay between frames is
34 milliseconds.


Examples below are with RICOH THETA SC2 with firmware 1.64


With no options, will save 5 frames at 1 fps.

tpreview.exe sc2SaveFrames

live preview screenshot

Changing number of frames and delay between frames

Saving 10 frames with a delay of 10 seconds between frames. 10 seconds
is 10000 milliseconds.

Example shown using dart command on uncompiled application in bin\tpreview.dart.
Test with SC2 firmware 1.64.

\tpreview\bin> dart .\tpreview.dart saveFrames --frames=10 --delay 10000
frame 0
total bytes received 0.063492MB

In the example above, I am holding the camera up to my computer monitor
to test a moving scene. I am playing a moving from YouTube on my
computer screen for the motion.

Z1 test

With firmware 2.00.1, the test results are the same.

Each frame can be viewed in a viewer such as FSP Viewer.

Setting Resolution and fps with the API

You cannot use the WebAPI to change the resolution or framerate of the SC2.
The API for previewFormat only works with the V and Z1.

Set to 1920x960 @ 8fps

dart .\tpreview.dart previewFormat --width=1920 --framerate=8

Save frames and verify.


tpreview state

  "fingerprint": "FIG_0003",
  "state": {
    "batteryLevel": 0.8,
    "storageUri": "",
    "_apiVersion": 2,
    "_batteryState": "charged",
    "_cameraError": [],
    "_captureStatus": "idle",
    "_capturedPictures": 0,
    "_latestFileUrl": "",
    "_recordableTime": 0,
    "_recordedTime": 0,
    "_function": "normal"

tpreview takePicture

  "id": "68",
  "progress": {
    "completion": 0.0
  "state": "inProgress"

dart tpreview.dart info

This example shows how to run the bin/tpreview.dart source file instead of the compiled binary. The compiled binary will run faster.

  "manufacturer": "RICOH",
  "model": "RICOH THETA SC2",
  "serialNumber": "20001005",
  "firmwareVersion": "01.64",
  "supportUrl": "https://theta360.com/en/support/",
  "gps": false,
  "gyro": true,
  "endpoints": {
    "httpPort": 80,
    "httpUpdatesPort": 80
  "apiLevel": [
  "api": [
  "uptime": 3294,
  "_wlanMacAddress": "58:38:79:2b:ad:c5",
  "_bluetoothMacAddress": "6c:21:a2:47:d9:05"

Example Compiling for Windows

dart compile exe --output build/tpreview.exe .\bin\tpreview.dart
Info: Compiling with sound null safety
Generated: c:\users\craig\documents\development\ricoh\livepreview\tpreview\build\tpreview.exe

Usage after compilation

cd .\build\
.\tpreview.exe info   

frame conversion to video for testing

Combined frames into video with movie editor to test smoothness and check for broken frames.

SC2 example

Read about limitations using dio with the SC2.
The application provides an example using the Dart package http that works with the SC2.

Using http with the SC2 has a problem with the error
Connection closed before full header was received.

This appears to be a known issue with Dart and Flutter.

The application appears to work despite the error.

Use with mobile apps

The application uses a package theta that can be used with Flutter.

Instructions on using with Flutter

Steps to use with Flutter.

  1. create stream controller
  2. pass controller to either getLivePreview for Z1/V or sc2GetLivePreview
  3. use StreamBuilder to take the stream
  4. convert list of bytes to Uint8List
  5. pass the bytes to Image.memory()
  6. enable gaplessPlayback

Flutter Example for Z1 / V

  Widget build(BuildContext context) {
    StreamController controller = StreamController();
    Preview preview = Preview(controller);
    preview.getLivePreview(frames: 300);
  return Scaffold(
// your GUI code here
 child: StreamBuilder(
  stream: controller.stream,
  builder: (BuildContext context, AsyncSnapshot snapshot) {
    if (snapshot.hasData) {
      var imageData = Uint8List.fromList(snapshot.data);
      return Image.memory(
        gaplessPlayback: true,
    } else {
      return Container();

SC2 Example

WARNING: SC2 library is only partially working. Do not use in production applications. This is for testing and demonstration only.

Sc2Preview preview = Sc2Preview(controller);
preview.getLivePreview(frames: 300);


  • Sept 29, 2021: using different getLivePreview functions for SC2 and V/Z1.
  • Sept 19, 2021: tested with Z1 and appears to work fine.
  • Sept 18, 2021: live preview save to frames is working with SC2

I’ve been using tpreview over the past week, both as a command line tester, where I find it to be super useful, and as part of a Flutter mobile app.

I used tpreview to test my V, Z1 and SC2 with displaying thumbnails. There’s clearly a difference among the three cameras. I will post a full video on Wednesday.

I am also working on building a Flutter mobile app. Compared to the command line tool, which I like, for seeing the camera in action - specifically seeing the livePreview - it’s just great.

Following the video that @craig posted here, I could add functionality buttons, and see the livePreview running in my app.

I’m working more with it this week. I’ll post some screenshots here.

1 Like

I extended the original tutorial demonstration of Oppkey THETA API Test Kit to show it running on a physical device Android phone in both landscape and portrait modes.

great to hear that you used tpreview (soon to be renamed opptheta) to test the live preview API settings. Perhaps like me, you were surprised by the differences between the RICOH THETA V/Z1 models and the SC2?

1 Like

I extended the demo again to show how to move the buttons to the left of the screen.

3 button examples in landscape mode

1 Like

Hey. I tried your package with SC2, unfortunately when live streaming, sometimes I am getting the error “Invalid Image Data”. Do you know how to solve this? Thanks

I do not have a stable Flutter implementation with the SC2. I can get all the frames from the camera with Dart, but I believe that Flutter is dropping some of the frames.

You may need to use the official SDK:

In my Flutter tests, I have only tested that the SC2 API can deliver the frames to the device. I have not figured out a way to eliminate the flicker.

This problem started to occur with Flutter 2.0 when it moved to null-safety.

At the current time, it may be better to use a native implementation for the SC2.

For the V, Z1, and likely X, you can have some additional algorithm to check the frame and make sure it is valid JPG. However, on the SC2, there were too many frames that were bad. In a separate test, I downloaded and saved all the frames from the SC2. So, I know I am getting the frames in my app. I just can’t display it smoothly.