Documentation
This will be the main entry point to documentation, with table of contents and links to translations.
General documentation is to be found here. The following is a summary + some issue solving.
- Check if you have a running Java JDK 11+,
- Download the latest release (alternatively, you can build the application),
- Unzip the distribution archive,
- Run the launcher script: either studio-linux.sh, studio-macos.sh or studio-windows.bat depending on your platform. You may need to make them executable first,
- If it does not open automatically, open a browser and type the url http://localhost:8080 to load the web UI.
Note: avoid running the script as superuser/administrator, as this may create permissions issues.
On Windows, this application requires the libusb driver to be installed. The easiest way to achieve this is to have the official Luniistore* software installed (but not running).
In some cases you may need to tweak the launcher script "studio-windows.bat".
If you have several JDK or SDK installations on your Windows, it may happen that things got messed up. To solve this, you can manually set the path to your Java JDK by adding this line after the @echo off
SET PATH="C:\Program Files\Java\jdk-14.0.1\bin" (please check your own jdk path)
I you moved your Windows user profile, chances are Studio can't find it anymore. In this case, change the relative DOT_STUDIO path %UserProfile%.studio to the absolute path of your user profile.
set DOT_STUDIO=D:\Users\johndo\.studio (change path according to your own)
Before you start making your own story packs, you may want to understand what it's made of, and what the Story Teller expects. Here is a brief introduction to the story pack structure.
If you are just interested in making a (relatively simple) story pack, you can skip this part and go directly to the "simplified mode" chapter. Simplified nodes encapsulate the most common behaviors you may want to use, without needing a deep understanding of the structure of a story pack. I recommend you take a look at the example pack (which is already loaded when you open the editor).
To put it simply, a story pack is a tree of two types of nodes:
- Stage Nodes, which can play an audio file and/or display an image,
- Action Nodes, which can be seen as a "menu", or a list of Stage Nodes available to the user at one point.
The root of the tree is a Stage Node, it contains the images and audio that are played by the Story Teller when the user is choosing a story pack. You can see it as the "cover" of your pack.
To let the user interact with your story, you must define the behavior when OK and HOME buttons are pressed. This transition is handled by linking the button to an Action Node. The first "menu item" (a Stage Node) will be played (or you can choose to play another item). At this point, the Action Node now controls which items are available to the user through the scroll wheel: moving the wheel left or right will navigate through all the "menu items".
You can chain Stage Nodes and Action Nodes however you like, but keep in mind the "golden rule": a Stage Node can only transition to an Action Node, and an Action Node contains a list of Stage Nodes only.
You'll see that there are more subtleties, that you can control what the user can or cannot do at any point in your story pack, but I'll leave this for another part of the documentation.
The editor is the place where you make story packs. It is composed of three panels :
- Top panel, header of your story with file name, version, UUID, comments, thumbnail and options to Save | Import | Export | Clear pack,
- To the left, a toolbox of nodes that you can drop-and-drop to compose your story pack,
- To the right, a canvas containing the graph defining your story pack.
Once you have created your first story from the Main Layout, the button to create a new one will disapear. To create a new story, you can either change an existing story name from the header to make a copy and/or use the Clear pack button
-
Opt out of announces: When opening the web UI, an announce may be displayed, if it is newer than the build time and the last display time. This is a way to communicate information to the users, such as an important update or in case a device-bricking bug appeared later on. This setting is an opt-out.
-
Allow enriched binary format (includes metadata): The binary/raw format supported by the lunii device does not contain as much metadata as you can have with the editable archive format. With this option, you can add such metadata while remaining compatible with the device. The added metadata are: the pack title and description (potentially truncated), nodes name (potentially truncated), group identifier, type, and position in the graph. This makes it possible to recover more data when converting back from the device into the editor. This works only for "binary / raw / lunii firmware v1" format for now, but could also support the newer "fs / lunii firmware v2" format in the future.
The toolbox contains 5 types of nodes from which to choose. This chapter is here to help you choose which one fits your situation.
Simplified nodes encapsulate the most common behaviors you may want to use, without needing a deep understanding of the structure of a story pack.
A story pack may only contain one Cover Node. It contains the images and audio that are played by the Story Teller when the user is choosing a story pack.
A Menu Node can be used to ask a question to the user, and offer them a list of options to choose from. Each option can transition to a different node, be it a Story Node or even another Menu Node.
A Story Node only plays audio, and automatically goes back to the start of the story pack when done playing.
Stage and action nodes are closely tied to the file format understood by the Story Teller. These nodes are not very intuitive to work with, and give you the most flexibility. Be sure to know what you are doing or you may shoot yourself in the foot.
You can mix and match expert nodes with simplified nodes if you see fit. The editor got your back and won't let you make invalid links that do not follow the "golden rule".
A Stage Node can play an audio file and/or display an image. There are a few options you can toggle to control what the user can or cannot do:
- Allow wheel selection: whether the user can or cannot navigate the current "menu" / Action Node's list (you may want to disable this when playing a question or a story),
- Allow OK button: whether the user can press OK (you may want to disable this when playing a question or a story),
- Allow HOME button: whether the user can press HOME (you may want to disable this when playing a question),
- Allow PAUSE button: whether the user can press PAUSE (you may want to enable this when playing a story),
- Enable autoplay: whether the Story Teller should automatically play the OK transition when the audio file is done playing (you may want to enable this when playing a question or a story).
An Action Node is simply a list of items, each item pointing to a Stage Node. It may be used to create a "menu" from which the user can choose an option (when the wheel is enabled), or as a repository of stories or questions to play, or simply to transition from a Stage Node to another.
Image files may use the following formats (formats marked with asterisks are automatically converted when transferring to the device) :
PNG JPEG BMP (24-bits) Image dimensions must be 320x240. Images may use colors, even though some colors may not render accurately due to the screen being behind the plastic cover. Bear in mind that the color of the cover may change.
Audio files may use the following formats (formats marked with asterisks are automatically converted when transferring to the device) :
MP3 OGG/Vorbis WAVE (signed 16-bits, mono, 32000 Hz) MP3 and OGG files are expected to be sampled at 44100Hz.
Image files may use the following formats (formats marked with asterisks are automatically converted when transferring to the device) :
PNG JPEG BMP (24-bits) Image dimensions must be 320x240. Images may use colors, even though some colors may not render accurately due to the screen being behind the plastic cover. Bear in mind that the color of the cover may change.
Audio files may use the following formats (formats marked with asterisks are automatically converted when transferring to the device) :
MP3 OGG/Vorbis WAVE (signed 16-bits, mono, 32000 Hz) MP3 and OGG files are expected to be sampled at 44100Hz.
Audio files will be correctly rendered by device if peak is normalized at 0dB
If you have a lot of audio to record on linux, this small command line script will do the recording and the normalization:
# Record sound via command line, press Ctrl+C to stop
arecord --rate 44100 -vv -fdat /tmp/out.wav
# Compute needed gain
A=$(echo "-0.1-( $(ffmpeg -i /tmp/out.wav -af 'volumedetect' -f null /dev/null 2>&1|grep max_volume|cut -f 5 -d" ") )"|bc -l)
# Convert to mp3 and ajust volume
ffmpeg -i /tmp/out.wav -vn -af "volume=${A}dB" /tmp/out.mp3
# Move file to output and clean
mv -f /tmp/out.mp3 $1
rm /tmp/out.wav* Lunii is a registered trademark of Lunii SAS. I am (and this work is) in no way affiliated with Lunii SAS.