Skip to content

feat: Add "Quiet Library" batched word-by-word transition#711

Open
wonkybutt wants to merge 12 commits into
Fiestaboard:mainfrom
wonkybutt:main
Open

feat: Add "Quiet Library" batched word-by-word transition#711
wonkybutt wants to merge 12 commits into
Fiestaboard:mainfrom
wonkybutt:main

Conversation

@wonkybutt

Copy link
Copy Markdown

Description

This pull request introduces the quietLibrary transition strategy, designed to update the board with the minimum possible mechanical noise. The behavior is modeled after the split-flap board in the Qantas First Class lounge at the Sydney airport, where the display updates methodically one word at a time to maintain a quiet environment.

To achieve this specific acoustic profile on the Vestaboard hardware, a custom row-by-row, word-by-word diffing algorithm was implemented.

List of Modifications:

  • Word Boundary Isolation: The algorithm scans the 6x22 grid and groups contiguous modified characters (and trailing spaces) into isolated word blocks.
  • Micro-Batching (Max 6 Characters): To prevent the sharp sound of an entire word updating simultaneously, modifications within a word block are subdivided into batches of 6 characters or fewer. The logic ensures a single batch never spans across two separate words.
  • Hardware Debounce Bypass (14.5s Delay): The Vestaboard hardware utilizes an internal debounce timer and takes up to 14 seconds to complete a full flap rotation. Incoming API payloads are dropped if received while the flaps are spinning. To guarantee sequential processing, a strict 14.5s delay is enforced between network requests.
  • Background Threading: Because transitioning the board in micro-batches with 14.5-second intervals can take several minutes, the execution logic in board_client.py is offloaded to a background thread. This prevents the Next.js web interface from blocking or timing out.
  • UI & API Integration: The quietLibrary strategy is added to backend API schemas, Next.js UI transition settings, and the translation dictionary (en.json).
  • Docker Config: Restored/added the docker-compose.yml file to ensure local testing environments spin up correctly.

Related Issue

N/A

Type of Change

  • Bug fix
  • New feature
  • New plugin
  • Documentation update
  • Refactor / maintenance

Checklist

  • I have tested my changes locally
  • I have added/updated tests where applicable
  • I have updated documentation where applicable
  • My code follows the project's coding standards

Adam Gulkis and others added 10 commits May 4, 2026 09:38
- Added quietLibrary strategy to backend API schemas and models
- Updated Next.js UI transition settings and translation dictionary
- Implemented _send_quietlibrary_transition in board_client.py for word-by-word diffing
- Offloaded transition logic to a background thread to prevent UI blocking
- Enforced a 14.5s request delay to bypass hardware debounce timers and ensure mechanical flap rotation completes
- Fixed duplicate key formatting errors in docker-compose.yml
Changes to the docker-compose were made for debugging. They are not part of the feature.

Signed-off-by: wonkybutt <vidarr@mac.com>
feat: Add "Quiet Library" word-by-word transition
- Modified quietLibrary transition to strictly isolate word boundaries
- Subdivided word updates into payload batches of 6 or fewer characters
- Prevents excessive simultaneous mechanical flap noise
- Ensures batches never span across two separate words
- Maintains the mandatory 14.5s hardware debounce delay between chunks
feat(transitions): limit quietLibrary updates to 6 chars per batch
fix(transitions): restore original file structure and correctly integ…
chore: add docker-compose.yml to version  control
@jeffredodd

Copy link
Copy Markdown
Member

Hey @wonkybutt thanks for the contribution! I think this is a really great idea but am also trying to think of the best way to implement this. The transitions you're trying to extend relate directly to the Vestaboard's local API and parameters it receives when we set them to various things like row transition. So because these classes are meant to mirror what Vestaboard provides I'm not sure it's the right spot for this to live long term.

But what I'm thinking is there is a need for some filter/animation/sequencer (Not sure on a name yet) that allows you to do just what you're trying to do, provide a frame by frame update, at a given interval, to produce an effect.

Anyways, give me a bit to noodle on this and I might want to build upon this idea if thats ok with you. Thanks again!

@roblesi

roblesi commented May 10, 2026

Copy link
Copy Markdown
Member

Hey @wonkybutt thanks for the contribution! I think this is a really great idea but am also trying to think of the best way to implement this. The transitions you're trying to extend relate directly to the Vestaboard's local API and parameters it receives when we set them to various things like row transition. So because these classes are meant to mirror what Vestaboard provides I'm not sure it's the right spot for this to live long term.

But what I'm thinking is there is a need for some filter/animation/sequencer (Not sure on a name yet) that allows you to do just what you're trying to do, provide a frame by frame update, at a given interval, to produce an effect.

Anyways, give me a bit to noodle on this and I might want to build upon this idea if thats ok with you. Thanks again!

+1

@jeffredodd

Copy link
Copy Markdown
Member

@wonkybutt just an update here. We're going to expose transitions that can be extended via plugin. The idea here is that you can write plugins that will transition your Vestaboard from one state to another. That puts the keys in your hands for how to handle updates coming in during a transition, as well as other config settings for your transition since I think everyone is going to want to tweak things per plugin.

Anyways stay tuned it's on our roadmap.

@wonkybutt

Copy link
Copy Markdown
Author

@jeffredodd Oh awesome! I was just starting to think about sending specific transitions based on different content. Looking forward to see what's possible!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants