Lunii.QT

A Python QT app to manage Lunii and Flam Storytellers, including reorder / import / export / hide / firmware download
for Windows / Linux / macOS
(compatible with STUdio archive, with transcoding)

Hardware supported:

v1, v2 (full Support)
v3 (export requires device key file)
Flam (partial support, only reorder and firmware backup)

Limitations

Application no longer allows Official stories to be exported
Audio transcoding requires FFMPEG v6 to be present (more details)

User Interface

.

Description

The menu bar. It will notify you when an update is available
(just get it with Menu About/Update to v2.X.X)
The location of your Lunii/Flam when it's connected.
The button on the left updates automatic detection.
Official DB refresh : Updates the list of stories and related information from the official Lunii Store. Use it when some official are not recognized.
The list of your stories with UUID and Database (DB) origin.
The UUID: This unique identifier allows you to associate stories with their folder on the Lunii, thanks to the last eight characters that make up the name of the folder associated with that story.
- DB stands for Database. This application supports two different databases
  - O - Lunii Official Database
    (all metadata are fed from Lunii servers)
  - T - Thirdparty Database, also known as Unofficial or Custom Stories
    (Those metadata can't be fetched. They are completed upon story import)
The status bar, you'll find
- your SNU (serial number)
- the firmware version of your Lunii/Flam
- the available space
- the number of stories it contains
Hidden stories (greyed items in the list) are still stored on the device, but won't be visible by Luniistore app. That will avoid getting third party stories to be removed during synchronization. Just remember to hide them before hitting sync button !

Shortcuts

Keys	Actions
`Ctrl+Up`	Move the selected item(s) Top
`Alt+Up`	Move the selected item(s) Up
`Alt+Down`	Move the selected item(s) Down
`Ctrl+Down`	Move the selected item(s) Bottom

`Ctrl+I`	Import new story
`Ctrl+S`	Export the selection
`Ctrl+Shift+S`	Export all the stories
`Ctrl+H`	Hide/Show selected stories
`Delete`	Remove the selected item(s)

`Ctrl+O`	Open a Lunii/Flam device
`Ctrl+L`	Open debug log window
`Ctrl+Q`	Exit the application
`F1`	About the app
`F5`	Refresh devices

Features

Automatic Update detection
Import / Export / Remove stories
Support STUdio archive formats, and import STUdio database
Reorganize the stories in the order you want
Hide stories
In order to avoid stories to get removed by Luniistore PC Synchronization, you can temporary hide them (all files ares kept on device), sync, and revert hide.
Lost Stories
Three tools are offered to manage "crashed" stories on your device.
You can :
- List them
  (app will try to fix broken stories, in particular auth files on v1/v2)
- Recover them (if they are complete)
- Remove them (be careful, files will be deleted)
Get Firmware for your device (refer this section)

Audio Transcoding

Some third-party stories are using non MP3 files. Thus they can't be installed as it is on Lunii. It requires a transcoding step. This extra process is done using FFMPEG tool ( https://ffmpeg.org/download.html )

WARNING : transcoding is very long, you should be patient. That's why you should prefer the .plain.pk format that use compatible audio.

Installation

Windows

NOTE : By default, from now on, the Windows portable and MSI will embed FFMPEG 6.1.1

Procedure:

grab your ffmpeg release from here
rename it to ffmpeg.exe
copy beside lunii-qt.exe
```
- 
 |- lunii-qt.exe
 |- ffmpeg.exe
```
restart luni-qt

Alternate method (I prefer):

open powershell terminal

run the following commands to install Scoop Package manager

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression

install ffmpeg with
scoop install ffmpeg
restart luni-qt

Linux

open a terminal
run following command :
sudo apt-get install ffmpeg
restart luni-qt

macOS

To ease ffmpeg tool installation, it is recommended to use Brew from https://brew.sh/

open a terminal
copy and paste the following link
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
At the end of the installation, type into the terminal:
brew install ffmpeg
restart luni-qt

Checking

Within the application, the Tools menu will display the status of detection.

Not found

Found

Firmware upgrade

Lunii.QT offers you the possibility to backup and upgrade your Firmware without connecting to LuniiStore (you won't lost your non official loaded stories). This procedure is experimental but so far no one faced issues.

NOTE 1: Remember to keep a backup of your firmware for Lunii v3 and FLAMs, in cas of a release that would break to third party stories trick. You will be able to downgrade.
NOTE 2: You cannot choose the firmware version. You'll only get the latest available from Lunii servers.

HowTo - Lunii

Select a Lunii/Flam device
Menu Tools/Get FW Update
You'll be prompted for login entry

Enter your Luniistore credentials (they are not saved for security purpose).
You can verify this point here

Lunii.QT/pkg/main_window.py

Lines 468 to 475 in a8bd30e

    
           login_dialog = LoginDialog() 
        
           if login_dialog.exec_() != QDialog.Accepted: 
        
               return 
        
           login, password = login_dialog.get_login_password() 
        
           try: 
        
               # getting auth token 
        
               auth_token = lunii_get_authtoken(login, password)

Pick a location where to save your firmware(s) (there are two for Lunii v1)
Copy it to the root dir of your device
Rename it to fa.bin (and optionnally fu.bin for Lunii v1)

- 
 |- .contents
 |- .md
 |- .pi
 |- fa.bin
 |- ... (other files)

Power OFF, Power ON, Wait : TADA
(if you reconnect your lunii on your pc, the fa.bin should have been removed)

HowTo - Flam

Select a Flam device
Menu Tools/Get FW Update
You'll be prompted for login entry

Enter your Luniistore credentials (they are not saved for security purpose).
You can verify this point here

Lunii.QT/pkg/main_window.py

Lines 468 to 475 in a8bd30e

    
           login_dialog = LoginDialog() 
        
           if login_dialog.exec_() != QDialog.Accepted: 
        
               return 
        
           login, password = login_dialog.get_login_password() 
        
           try: 
        
               # getting auth token 
        
               auth_token = lunii_get_authtoken(login, password)

Pick a location where to save your firmwares (update-main.enc and update-comm.enc)
Copy them to the root dir of your device

- 
 |- etc/
 |- str/
 |- .mdf
 |- update-main.enc
 |- update-comm.enc
 |- ... (other files)

Create an empty file cable_update_complete in /tmp

- 
 |- etc/
 |- str/
 |- .mdf
 |- update-main.enc
 |- update-comm.enc
 |- tmp/
   |- cable_update_complete
 |- ... (other files)

Eject USB from Flam device (USB cable must be kept connected) and update process will start : TADA
(if you reconnect your flam on your pc, the *.enc should have been removed)

Supported archive formats (Lunii)

NOTE : Flam stories are not yet supported

.plain.pk

Filename : story_name.8B_UUID.plain.pk
Ciphering : None / Plain
Structure :

  uuid.bin
  ni
  li.plain
  ri.plain
  si.plain
  rf/000/XXYYXXYY.bmp
  sf/000/XXYYXXYY.mp3

.v1.pk / .v2.pk

Filename :

LONG_UUID.v2.pk
LONG_UUID.v2.pk
LONG_UUID.pk

Ciphering : Generic Key
Structure :

  00000000000000000000000000000000/ni
  00000000000000000000000000000000/li
  00000000000000000000000000000000/ri
  00000000000000000000000000000000/si
  00000000000000000000000000000000/rf/000/XXYYXXYY
  00000000000000000000000000000000/sf/000/XXYYXXYY

ZIP (old Lunii.QT)

Filename : 8B_UUID - story_name.zip
Ciphering : Generic Key
Structure :

  uuid.bin
  ni
  li
  ri
  si
  rf/000/XXYYXXYY
  sf/000/XXYYXXYY

ZIP (alternate)

Filename : AGE+] story_title DASHED_UUID.zip
Ciphering : Generic Key
Structure : (same as .v1.pk / .v2.pk)

  00000000-0000-0000-0000-000000000000/ni
  00000000-0000-0000-0000-000000000000/li
  00000000-0000-0000-0000-000000000000/ri
  00000000-0000-0000-0000-000000000000/si
  00000000-0000-0000-0000-000000000000/rf/000/XXYYXXYY
  00000000-0000-0000-0000-000000000000/sf/000/XXYYXXYY

7z

Filename : AGE+] story_title DASHED_UUID.7z
Ciphering : Generic Key
Structure :

  00000000-0000-0000-0000-000000000000/ni
  00000000-0000-0000-0000-000000000000/li
  00000000-0000-0000-0000-000000000000/ri
  00000000-0000-0000-0000-000000000000/si
  00000000-0000-0000-0000-000000000000/rf/000/XXYYXXYY
  00000000-0000-0000-0000-000000000000/sf/000/XXYYXXYY

STUdio (ZIP / 7z)

Filename : AGE+] story_title DASHED_UUID.zip .7z
Ciphering : None

Structure :

    assets/
    stroy.json
    thumbnail.png

Python ? HowTo

Prepare env

First, clone the git repo
Prepare a Virtual environment for your project and install requirements

$ python3 -m venv venv

Switch to your venv

on Linux
source venv/bin/activate
on Windows
.\venv\Scripts\activate.bat

Install dependencies ****``` $ pip install -r requirements.txt


**Linux** has one more extra dependency to be installed  

```bash
$ apt install libxcb-cursor0

Build UI files

$ pyside6-uic pkg/ui/main.ui -o pkg/ui/main_ui.py
$ pyside6-rcc resources.qrc -o resources_rc.py

Run

$ python lunii-qt.py

Build GUI executable

NOTE : PyInstaller by its design generates executables that are flagged by AntiViruses. Those are false positives. cx_Freeze is an alternative that allows to avoid such false positives.

PyInstaller 👎

$ pip install pyinstaller
$ pyinstaller lunii-qt.spec
...
$ dist\lunii-qt

cx_Freeze 👍

$ pip install cx_Freeze
$ python setup.py build_exe
...
$ build/exe.win-amd64/lunii-qt

Tricks

macOS - Application Authorization

Double-click the file called lunii-qt.
You should see an error message "lunii-qt can’t be opened because it is from an unidentified developer".

Click "OK"
Go to System Preferences > Security and Privacy and click on the General tab.
At the bottom of the window you will see a message saying that lunii-qt was blocked. Click "Open Anyway".
If you do not see this message in the General tab, double-click lunii-qt again.
NOTE : You may have to click the "unlock" button and enter your password to be able to click "Open Anyway".
If you see another popup that says “lunii-qt is from an unidentified developer. Are you sure you want to open it?”, click "Open". If you don’t get this popup, just go to the same file and double-click it again.
Finally, you'll be informed that lunii-qt was downloaded from internet

Click "Open", and you'll never get these messages in the future.

Third Party story metadata

You might have already loaded non-official stories to your device thanks to another app. When opening Lunii.QT, this story will appear as Unknown story (maybe a User created story)....
You can easily fix that by :

Importing STUdio DB with menu File/Import STUdio DB
Dropping the corresponding archive as you'll do for loading.
Lunii.QT will only read the metadata and add them locally, skipping the rest of the archive.

Cache management

This application will download once for all the official story database and any request pictures to the application dedicated folder

$HOME/.lunii-qt/official.db
$HOME/.lunii-qt/cache/*

In case of any trouble, just remove this file and directory to force refresh

v3 export

In order to suport story export from Lunii v3 hardware, you must place your device keys in here :

%HOME%\.lunii-qt\v3.keys
$HOME/.lunii-qt/v3.keys

It is a binary file with 0x10 bytes for Key and 0x10 bytes for IV

ICO creation

magick convert logo.png -define icon:auto-resize="256,128,96,64,48,32,16"  logo.ico

Credits

Thanks to :

olup for STUdio archive format
sniperflo for v1 support, MacOs support & debug
McFlyPartages for Linux debug and other contributions

Links / Similar repos

Lunii v3 - Reverse Engineering
Lunii CLI tool
STUdio - Story Teller Unleashed
(GitHub) STUdio, Story Teller Unleashed
Lunii Admin (a GO implementation of a STUdio alternative)
Lunii Admin Web (same as previous but from a browser)
Icon trick for workflow using rcedit

Name		Name	Last commit message	Last commit date
Latest commit History 244 Commits
.github/workflows		.github/workflows
pkg		pkg
res		res
tools		tools
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README_FR.md		README_FR.md
lunii-qt.darwin.spec		lunii-qt.darwin.spec
lunii-qt.py		lunii-qt.py
lunii-qt.spec		lunii-qt.spec
make_release.ps1		make_release.ps1
requirements.txt		requirements.txt
resources.qrc		resources.qrc
resources_rc.py		resources_rc.py
setup.py		setup.py

	login_dialog = LoginDialog()
	if login_dialog.exec_() != QDialog.Accepted:
	return
	login, password = login_dialog.get_login_password()

	try:
	# getting auth token
	auth_token = lunii_get_authtoken(login, password)

License

o-daneel/Lunii.QT

Folders and files

Latest commit

History

Repository files navigation