mcflypartages / lunii.qt

A Python QT app to manage Lunii Storyteller

🇫🇷 README en francais 🇫🇷

Lunii.QT

A Python QT app to manage Lunii Storyteller, including reorder / import / export / firmware download
for Windows / Linux / MacOs 11
(compatible with STUdio archive, with transcoding)

Hardware supported:

• v1, v2 (full Support)
• v3 (export requires device key file)

Limitations

• Application no longer allows Official stories to be exported
• Audio transcoding requires FFMPEG v6 to be present (link to section)
• Flam not yet supported (next update might)

Table of contents

• Lunii.QT
  • User Interface
  • Shortcuts
  • Audio Transcoding
  • Firmware upgrade
  • Supported archive formats
  • Python ? HowTo
  • Trick
  • Credits
• Links / Similar repos

User Interface

.

Description

1. The menu bar. It will notify you when an update is available
   (just get it with Menu About/Update to v2.X.X)

2. The location of your Lunii when it's connected.
   The button on the left updates automatic detection.

3. Official DB refresh : Updates the list of stories and related information from the official Lunii Store. Use it when some official are not recognized.

4. 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)

5. The status bar, you'll find

   • your SNU (serial number)
   • the firmware version of your Lunii
   • the available space
   • the number of stories it contains

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
Delete	Remove the selected item(s)
Ctrl+O	Open a Lunii device
Ctrl+L	Open debug log window
F1	About the app
F5	Refresh devices

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 available here :
https://github.com/eugeneware/ffmpeg-static/releases/latest

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

Installation

You must ensure that ffmpeg command is in your path.
If you're lost, just can grab a standalone binary on the previous link, for you platform (Win/Linux/MacOs), and copy it beside this app, like this :

- 
 |- lunii-qt.exe
 |- ffmpeg.exe

1. Grab your ffmpeg release
2. Rename it to ffmpeg.exe or ffmpeg (depending on your host OS)
3. Copy beside lunii-qt.exe

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

1. Select a Lunii device
2. Menu Tools/Get FW Update
3. You'll be prompted for login entry
   
4. Enter your Luniistore credentials (they are not saved for security purpose).
   You can verify this point here main_window.py#L468
5. Pick a location where to save your firmware version
6. Copy it to the root dir of your lunii
7. Rename it to fa.bin

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

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

Supported archive formats

.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

TODO

• add Flam support ?
• improve 7z archive processing
• config file to backup menu config (sizes / details)
• add picture to tree list ?

Python ? HowTo

Prepare env

Prepare a Vitrual environment for your project and install requirements

$ python -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

$ 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

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

Trick

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 & debug
• McFlyPartages for Linux debug and other contributions

Links / Similar repos

• Lunii v3 - Reverse Engineering
• 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)