diff --git a/scripts/README.md b/scripts/README.md index 9657ee3..9bdafd9 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -8,7 +8,7 @@ These are tools for the repository. None of them is in the wheel. | `cardputer-zero/` | `build-deb.sh` builds the Debian package for M5Stack's app store. Run it on the Cardputer Zero or on another arm64 Debian 13 system. `store/` holds the listing for the store (`app-builder.json`, which `czdev publish` reads), its icon, and its screenshots. `screenshot.py` saves the display of a Cardputer as a 320×170 PNG over SSH, as the store wants a screenshot. `store-publish.py` sends a package to the store with M5Stack's `czdev`, with two corrections. The release workflow runs it after each release. `launcher-entry.sh` puts a source checkout in the Cardputer Zero's app launcher. `remove` takes it out. `meshterm.png` is the package's icon: the website's logo, at the launcher's 100×100 size. `meshterm-dev.png` is its negative, for the checkout's entry, so that the two entries look different. `type-text.py` types a pasted string (an API key, a Wi-Fi password) on the Cardputer's keyboard from another computer, over SSH | | `screenshots.py` | Makes the screenshots of the website from the demo mesh (`--demo`): the main menu, the chat, the paths of a message, and the map, for the terminal, the Cardputer Zero, and the PicoCalc. They are the same at each run. The result goes to `docs/screenshots//`. It also draws the two wordmarks of the splash into `docs/screenshots/splash/`, which the website uses as its splash | | `video.py` | Makes the demo video of the website from the demo mesh: a tour of less than two minutes in the terminal, with its poster and its play card. The result goes to `src/` of the `meshterm.net` checkout beside this one | -| `reels.py` | Makes the videos for Instagram from the demo mesh: one vertical video for each feature, with subtitles in the picture and no sound, a cover, and a caption for the post. The result goes to `output/reels/` | +| `reels.py` | Makes the videos for Instagram from the demo mesh: one vertical video for each page, with subtitles in the picture and no sound, a cover, and a caption for the post. The tours are in `reel_tours.py`. The result goes to `output/reels/` | | `picocalc-lyra/` | Setup of the Calculinux device: console font, palette, Wi-Fi. `xiao-radio/` is the kit for the XIAO radio (firmware build, flashing, UART setup) | | `uconsole/` | The uConsole's always-on SPI bridge service. MeshTerm can also control that radio directly, with no script (refer to `docs/devices/uconsole.md`) | @@ -118,25 +118,30 @@ the `meshterm.net` repository). ## reels.py -This script makes the videos for Instagram. Each video shows one feature of MeshTerm, in -the demo mesh. It is a Reel: a vertical video of 1080×1920 pixels, at 30 video frames each -second. The terminal has 72 columns, so that its text is as large as the width of a phone -lets it be. Above the terminal is the name of the series (`MeshTerm for MeshCore · Chat`), and under it -are the subtitles. The video has no sound, because many people watch Instagram with the -sound off. It ends on a card with the wordmark and the address of the website. +This script makes the videos for Instagram: one for each page of MeshTerm, in the demo mesh. +The written pages (About MeshTerm, About the author, Join Discord, and Support MeshTerm) +have no video. Each video is a Reel: a vertical video of 1080×1920 pixels, at 30 video +frames each second. The terminal has 72 columns, so that its text is as large as the width +of a phone lets it be. Above the terminal is the name of the series +(`MeshTerm for MeshCore · Chat`), and under it are the subtitles. The video has no sound, +because many people watch Instagram with the sound off. It ends on a card with the wordmark +and the address of the website. ```bash -python scripts/reels.py chat # into output/reels/ +python scripts/reels.py all # each video, into output/reels/ +python scripts/reels.py chat map # only these two python scripts/reels.py chat --out some/folder -python scripts/reels.py chat --recording chat.pickle # keep the recording +python scripts/reels.py all --recordings some/folder # keep the recordings ``` -`chat` is the only video now: the list of the conversations, a message that arrives, the -paths of a message, a mention and its answer, and a link as a QR code. To add a video, write -its tour and add it to `REELS`. A tour types the keys, as in `video.py`, and also writes the -subtitles (`Director.subtitle`). +The tours are in `reel_tours.py`, with the subtitles and the caption of each video, in the +`REELS` table. To add a video, write its tour and add it to `REELS`. A tour types the keys, +as in `video.py`, and also writes the subtitles (`Director.subtitle`). It opens its page +off camera, so that the video starts on the page. -The script writes three files: `.mp4` (the video, with a silent audio track), -`-cover.png` (the cover of the Reel), and `.txt` (a caption for the post). It -needs the same things as `video.py`, but not the website checkout. A run takes -approximately two minutes. +For each video, the script writes three files: `.mp4` (the video, with a silent audio +track), `-cover.png` (the cover of the Reel), and `.txt` (a caption for the +post). It needs the same things as `video.py`, but not the website checkout. One video +takes approximately two minutes, and all of them approximately 45 minutes. With +`--recordings`, the script keeps each recording in that folder, and a later run paints and +encodes it again without MeshTerm. diff --git a/scripts/reel_tours.py b/scripts/reel_tours.py new file mode 100644 index 0000000..32f07bb --- /dev/null +++ b/scripts/reel_tours.py @@ -0,0 +1,823 @@ +# SPDX-License-Identifier: Apache-2.0 +r"""The tours of the videos for Instagram: one or more for each page of MeshTerm. + +``scripts/reels.py`` records, paints, and encodes them. Each tour gets a director (refer to +``reels.Director``): it types the keys at the pace of a person, rolls the camera, and +writes the subtitles. A tour starts on its own page. It opens the page off camera, so that +the first video frame already shows the feature (a Reel has one or two seconds to keep a +viewer). + +A subtitle is short: two lines of approximately 26 characters at most. ``*text*`` is in +the brand colour, and ``\n`` starts the second line. The subtitles and the captions are +for viewers who do not know MeshTerm. Thus they use plain words: "name tag" instead of +"chip", for example. + +The written pages (About MeshTerm, About the author, Join Discord, and Support MeshTerm) +have no video. They are text, and a video of text is not interesting. +""" + +from __future__ import annotations + +import time +from collections.abc import Callable +from dataclasses import dataclass +from typing import TYPE_CHECKING + +import screenshots +import video + +if TYPE_CHECKING: + from reels import Director + + +@dataclass(frozen=True) +class Reel: + """One video of the series. + + Attributes: + title: The name of the page, in the series line above the terminal. + tour: The keys of the tour, and the subtitles. + caption: The text of the post on Instagram. + background: Whether the demo device plays the background traffic of its world. A + page that shows the traffic live (the dashboard, the live feed) needs it. On the + other pages, it stays off: then the screen does not change while the tour waits + off camera, and the cut does not show. + """ + + title: str + tour: Callable[[Director], None] + caption: str + background: bool = False + + +#: The end of each caption: where the video comes from, the website, and the hashtags. +_FOOTER = ( + "\n\nFilmed in MeshTerm's demo mesh over Montréal (meshterm --demo). MeshTerm is a free," + " open-source MeshCore client for Windows, macOS, and Linux.\n" + "\n" + "meshterm.net\n" + "\n" + "#MeshCore #LoRa #OffGrid #MeshNetwork #Terminal #TUI #OpenSource\n" +) + + +def _caption(*paragraphs: str) -> str: + """The caption of a post: its paragraphs, then :data:`_FOOTER`.""" + return "\n\n".join(paragraphs) + _FOOTER + + +# --------------------------------------------------------------------------- Message + + +def chat(d: Director) -> None: + """The chat: the conversations, a live message, the paths, a mention, and a QR code.""" + from meshterm.demo import script + + d.open_page("chat", "pick a conversation") + d.start("Off-grid chat over *LoRa radio*,\nright in your terminal") + d.hold(2.8) + d.type("pub") + d.hold(0.5) + d.key("enter", pause=0.0) + d.wait_for(screenshots.PATHS_MESSAGE[2]) + d.subtitle("Everyone gets\ntheir own *colour*") + d.hold(2.6) + + offset, _, line = next(item for item in script.LIVE_CHANNEL if item[1] == "Public") + with d.off_camera(): + d.wait_until(video._start() + offset - 0.8) + d.wait_for(line.text, timeout=20) + d.subtitle("New messages arrive *live*,\nover the air") + d.hold(2.4) + + for _ in range(3): # Chloé, Félix, then Gabriel + d.key("up", pause=0.45) + d.hold(0.5) + # A key press can be lost while the transcript draws. The camera does not show the + # tries: it shows the dialog of the right message as it opens. + with d.off_camera(): + video._open_paths(d) + d.subtitle("See *every path* a message\ntook to reach you") + d.hold(2.2) + d.key("down", pause=1.4) + d.key("up", pause=1.4) + d.key("down", pause=0.5) + d.camera.mark("poster") + d.hold(1.6) + d.key("escape") + d.key("escape") # the first Esc closes the dialog, the second clears the selection + + d.subtitle("*Mentions* turn into\nname tags as you type") + d.hold(0.6) + # The mention is typed in full: the ] makes it a chip. + d.type("Hey @[Dave-Lachine], are you coming Saturday?") + d.hold(0.8) + d.key("enter", pause=0.0) + sent = time.monotonic() + d.wait_for("0/130") # the compose line is empty: the message went + d.hold(0.8) + # Dave answers after ``script.REPLY_DELAY_S``. The camera does not show most of the wait. + with d.off_camera(): + d.wait_until(sent + script.REPLY_DELAY_S - 0.6) + d.wait_for("be there at 2", timeout=30) + d.subtitle("When someone *mentions you*,\nyou get a ★") + d.hold(2.8) + + d.subtitle("Turn any link into a\n*QR code* for your phone") + d.hold(0.4) + d.walk_to("11:04") # our message with the link to the map + d.hold(0.7) + d.key(text="u", ctrl=True, pause=0.0) + d.hold(3.4) + + +def channels(d: Director) -> None: + """The channels: their activity, a QR code to share one, and the scope of a channel.""" + d.open_page("channels", "Channels · 4/8 slots") + d.start("All your channels,\nwith their *activity*") + d.camera.mark("poster") + d.hold(3.0) + d.key("enter", pause=0.0) # Public + d.wait_for("Channel — Public") + d.subtitle("Share a channel\nwith a *QR code*") + d.hold(1.4) + d.key("enter", pause=0.0) # Show QR code + d.wait_for("meshcore://channel/add") + d.hold(3.4) + d.key("escape") + d.key("escape") + d.wait_for("Channels · 4/8 slots") + d.subtitle("Keep a channel's messages\nin *one region*") + d.key("down", pause=0.6) # #montreal, which has the scope mtl + d.key("enter", pause=0.0) + d.wait_for("Channel — #montreal") + d.hold(0.8) + d.walk_to("Send scope", "down", pause=0.3) + d.hold(0.5) + d.key("enter", pause=0.0) + d.capture.settle(quiet=0.8) + d.hold(3.2) + + +def rooms(d: Director) -> None: + """The rooms: the list, the board of a room, and a post that the room confirms.""" + d.open_page("rooms", "Rooms · 1 joined") + d.start("Join a room server's\n*message board*") + d.hold(2.4) + d.key("enter", pause=0.0) + d.wait_for("Room — MTL BBS") + d.hold(1.2) + d.key("enter", pause=0.0) # Open the board + d.wait_for("MTL BBS · member") + d.subtitle("Read the posts, also\nthe ones you *missed*") + d.camera.mark("poster") + d.hold(3.0) + d.subtitle("Then *post* to it") + d.type("I can bring two spare antennas on Saturday") + d.hold(0.6) + before = d.count("✓") + d.key("enter", pause=0.0) + d.wait_until_shows(lambda: d.count("✓") > before, timeout=20) + d.subtitle("The ✓ says the\nroom *got* your post") + d.hold(3.0) + + +def courier(d: Director) -> None: + """The courier: a message that waits until its contact is heard.""" + d.open_page("courier", "store-and-forward outbox") + d.start("Write now.\n*Deliver later.*") + d.hold(1.6) + d.key("enter", pause=0.0) # Queue a message… + d.wait_for("Courier — recipient") + d.hold(0.8) + d.type("sylvie") + d.hold(0.5) + d.key("enter", pause=0.0) + d.wait_for("Message for Sylvie-Gaspésie") + d.type("Welcome to the mesh! Ping me when you are on the air") + d.hold(0.6) + d.key("enter", pause=0.0) + d.wait_for("When should Sylvie-Gaspésie get it?") + d.subtitle("It goes when they are\n*next heard*, or at a time") + d.camera.mark("poster") + d.hold(3.0) + d.key("enter", pause=0.0) # "When it's next heard" + d.capture.settle(quiet=0.8) + d.subtitle("Until then, it waits\nin the *outbox*") + d.hold(3.2) + + +def contacts(d: Director) -> None: + """The contacts: a list to sort and filter, then the page of one node.""" + d.open_page("contacts", "Contacts · 40 known") + d.start("Every node you know,\nsorted *your way*") + d.hold(2.0) + d.key("right", ctrl=True, pause=1.3) + d.key("right", ctrl=True, pause=1.3) + d.type("mont-r") + d.hold(1.0) + d.key("enter", pause=0.0) + d.wait_for("Node — Mont-Royal") + d.subtitle("Each node has a page,\nwith its *map*") + d.hold(3.2) + d.key("tab", pause=0.0) + d.wait_for("node → you, as heard") + d.subtitle("and every *route*\nbetween you and it") + d.camera.mark("poster") + d.hold(3.4) + + +# --------------------------------------------------------------------------- Watch + + +def dashboard(d: Director) -> None: + """The dashboard: the activity, the traffic, and the health of the radio.""" + d.open_page("dashboard", "Dashboard — mesh overview", settle=1.5) + d.start("Your whole mesh,\n*live*, on one screen") + d.camera.mark("poster") + d.hold(3.4) + d.subtitle("Every packet *counted*,\nby kind") + d.hold(3.0) + d.subtitle("and the *health*\nof your radio") + d.hold(3.0) + d.subtitle("Narrow it to\n*one region*") + d.type("s") + d.wait_for("· unscoped") + d.hold(1.6) + d.type("s") + d.hold(2.4) + + +def livefeed(d: Director) -> None: + """The live feed: packets that arrive, and one packet opened.""" + from meshterm.demo import script + + d.open_page("live f", "Live feed") + offset, _, _ = next(item for item in script.LIVE_CHANNEL if item[1] == "Public") + with d.off_camera(): + d.wait_until(video._start() + offset - 1.5) + d.start("Every packet,\nthe moment it *arrives*") + d.hold(4.5) + d.subtitle("Open one to see\n*where it came from*") + d.key("down", pause=0.6) + d.key("enter", pause=0.0) + d.wait_for("class ") + d.camera.mark("poster") + d.hold(3.6) + + +def watchtower(d: Director) -> None: + """The watchtower: the alerts, and a node to watch.""" + d.open_page("watchtower", "Watchtower — alerts") + d.start("Know when a node\n*goes quiet*") + d.camera.mark("poster") + d.hold(2.8) + d.subtitle("or when a *new node*\nshows up") + d.hold(2.6) + d.subtitle("Pick the nodes\nyou want to *watch*") + d.key("end", pause=0.4) + d.walk_to("Watch a node", "up", pause=0.3) + d.key("enter", pause=0.0) + d.wait_for("Silence and SNR rules will watch it") + d.hold(1.0) + d.type("ros") + d.hold(0.6) + d.key("enter", pause=0.0) + d.wait_for("Rosemont silence") + d.hold(3.0) + + +def timemachine(d: Director) -> None: + """The time machine: the history of the whole mesh, then of one node.""" + d.open_page("time m", "Time machine") + d.start("Everything your radio\nhas ever *heard*") + d.hold(1.8) + d.key("enter", pause=0.0) # The whole mesh + d.wait_for("the whole mesh ·") + d.subtitle("Day by day,\nand *hour by hour*") + d.camera.mark("poster") + d.hold(3.4) + d.subtitle("New nodes, and\nthe *busiest* day") + d.key("pagedown", pause=0.0) + d.hold(2.8) + d.key("escape") + d.wait_for("── Nodes ──") + d.type("villeray") + d.hold(0.6) + d.key("enter", pause=0.0) + d.wait_for("Villeray ·") + d.subtitle("and the story\nof *each node*") + d.hold(3.4) + + +# --------------------------------------------------------------------------- Explore + + +def map_(d: Director) -> None: + """The map: the nodes over the city, a search, and the streets around our node.""" + capture = d.capture + d.open_page("map", "Map ·", settle=3.0, timeout=120) + capture.settle(quiet=3.0, timeout=120) + d.start("Every node on a\nreal *street map*") + d.camera.mark("poster") + d.hold(3.0) + d.subtitle("Type a name\nto *find* a node") + d.type("lach") + capture.settle(quiet=0.8, timeout=30) + d.hold(2.2) + d.key("escape", pause=0.4) + d.subtitle("Zoom in, down\nto the *streets*") + d.key(text="l", ctrl=True, pause=0.0) # our node + capture.settle(quiet=0.8, timeout=30) + for _ in range(5): + d.key("pageup", pause=0.0) + capture.settle(quiet=0.6, timeout=30) + d.hold(0.7) + d.hold(2.4) + + +def walk(d: Director) -> None: + """The mesh walk: the links of our node, then of the repeaters that it hears.""" + d.open_page("mesh w", "Mesh walk") + d.start("*Walk* the mesh,\none link at a time") + d.camera.mark("poster") + d.hold(3.0) + d.key("enter", pause=0.0) # the strongest link: Villeray + d.wait_for("1 hop out") + d.subtitle("See who each repeater\nhears, and *how well*") + d.hold(3.0) + d.key("enter", pause=0.0) + d.capture.settle(quiet=0.8) + d.hold(2.6) + d.subtitle("and walk *home*\nin one key") + d.key(text="l", ctrl=True, pause=0.0) + d.wait_for("this device") + d.hold(2.4) + + +def trace(d: Director) -> None: + """A trace to Brossard, with the signal at each hop and the new records.""" + d.open_page("trace t", "pick a target") + d.start("Trace a route to\nany *repeater*") + d.hold(1.4) + d.type("brossard") + d.hold(0.4) + d.key("enter", pause=0.0) + d.wait_for("Trace — Brossard") + d.hold(1.6) + d.key("enter", pause=0.0) + d.wait_for("Per-hop me", timeout=30) # a records dialog can cover the end + d.capture.settle(quiet=0.5) + # The history stores walks of one byte for each hop. Thus this walk of two bytes is new, + # and its records go to the trophy case. + if d.shows("new record"): + d.subtitle("New *records* go to\nyour trophy case") + d.hold(3.0) + d.key("enter", pause=0.0) # Close + d.subtitle("See the *signal*\nat every hop") + d.hold(1.2) + d.key("pagedown", pause=0.0) + d.camera.mark("poster") + d.hold(3.4) + + +def tracepath(d: Director) -> None: + """Trace path: a route composed hop by hop, then traced.""" + d.open_page("trace p", "Trace path") + d.start("Build a route\n*hop by hop*") + d.hold(1.8) + d.walk_to("Compose path", "up", pause=0.3) + d.key("enter", pause=0.0) + d.wait_for("Next hop from") + d.hold(1.2) + for _ in range(4): # remove the route of the last walk + d.key("backspace", pause=0.3) + d.subtitle("MeshTerm suggests the\n*strongest* next hop") + d.hold(1.0) + for name, label in (("vill", "Villeray"), ("mont-r", "Mont-Royal"), ("rose", "Rosemont")): + d.type(name) + d.hold(0.4) + d.key("enter", pause=0.0) + d.wait_for(f"Next hop from {label}") + d.hold(0.9) + d.camera.mark("poster") + d.walk_to("Use this path", "down", pause=0.2) + d.key("enter", pause=0.0) + d.wait_for("one transmission") + d.subtitle("Then *trace* it") + d.hold(0.8) + d.walk_to("one transmission", "down", pause=0.3) + d.key("enter", pause=0.0) + d.capture.settle(quiet=1.5, timeout=30) + if d.shows("new record"): + d.subtitle("and set new *records*") + d.hold(2.6) + d.key("enter", pause=0.0) # Close + d.capture.settle(quiet=0.5) + d.hold(3.0) + + +def records(d: Director) -> None: + """The trophy case: the record lists, then one record, its route, and its area.""" + d.open_page("trophy", "Trophy case") + d.start("Every trace is *scored*") + d.hold(2.2) + d.subtitle("Your best walks,\nin the *trophy case*") + d.hold(2.2) + d.key("enter", pause=0.0) + d.wait_for("1st place") + d.hold(2.4) + d.key("tab", pause=0.0) + d.capture.settle(quiet=0.8) + d.subtitle("See the *route*\nit walked") + d.camera.mark("poster") + d.hold(3.0) + d.key("tab", pause=0.0) + d.capture.settle(quiet=0.8, timeout=60) + d.subtitle("and the *area*\nit covered") + d.hold(3.2) + + +# --------------------------------------------------------------------------- This node + + +def info(d: Director) -> None: + """Device info: the status of the radio and its settings.""" + d.open_page("device i", "Device info") + d.start("Your radio's *status*\nat a glance") + d.camera.mark("poster") + d.hold(3.4) + d.subtitle("and every setting,\n*explained*") + d.key("pagedown", pause=0.0) + d.hold(2.6) + d.key("pagedown", pause=0.0) + d.hold(2.6) + + +def config(d: Director) -> None: + """Device config: the settings, a location set on the map, and the staged changes.""" + capture = d.capture + d.open_page("device c", "Device config — Alex Base") + d.start("Change your radio's\n*settings*") + d.hold(2.2) + d.key("down", pause=0.6) # Pick location on map… + with d.off_camera(): + d.key("enter", pause=0.0) + d.wait_for("Set location") + capture.settle(quiet=2.5, timeout=120) + d.subtitle("Set your location\n*on a map*") + d.camera.mark("poster") + d.hold(1.6) + for _ in range(4): + d.key("left", pause=0.0) + capture.settle(quiet=0.4, timeout=30) + d.hold(0.3) + d.hold(1.0) + d.key("enter", pause=0.0) + d.wait_for("Device config — Alex Base") + d.hold(1.0) + d.subtitle("Nothing changes until\nyou *apply* it") + d.key("end", pause=0.0) + d.wait_for("staged change") + d.hold(3.2) + + +def advert(d: Director) -> None: + """Send advert: announce our node, or share it as a QR code.""" + d.open_page("send adv", "Announce this node to the mesh:") + d.start("Announce your node\nto the *mesh*") + d.hold(2.6) + d.subtitle("or share it as a\n*QR code*") + d.key("down", pause=0.5) + d.key("down", pause=0.6) + d.key("enter", pause=0.0) + d.wait_for("meshcore://contact/add") + d.camera.mark("poster") + d.hold(4.0) + + +# --------------------------------------------------------------------------- Other nodes + + +def repeater_admin(d: Director) -> None: + """Repeater admin: the settings of a repeater, read over the air, then its CLI.""" + from meshterm.core import preferences + + capture = d.capture + d.open_page("repeater a", "node to manage") + with d.off_camera(): + d.key("enter", pause=0.0) # Stade-Olympique, a remembered admin + d.wait_for("Repeater admin — Stade-Olympique") + capture.settle(quiet=0.8) + d.start("Run a repeater\n*over the air*") + d.hold(2.2) + d.key("end", pause=0.5) + d.walk_to("Read settings", "up") + d.hold(0.5) + d.key("enter", pause=0.0) + d.wait_for("Reading — Stade-Olympique") + d.subtitle("Read all its\n*settings*") + d.hold(2.2) + # The read is one round trip for each setting, with the transmit cooldown between two + # reads: more than three minutes in all. Off camera, a short cooldown makes the run + # shorter, and the video does not show it. + with d.off_camera(): + cooldown = preferences.current().trace_cooldown_s + preferences.current().set("trace_cooldown_s", 0.2) + try: + d.gone("Reading — Stade-Olympique") + finally: + preferences.current().set("trace_cooldown_s", cooldown) + capture.settle(quiet=0.5) + if d.shows("No reply from"): + d.key("enter") # the list of the settings that did not answer + capture.settle(quiet=0.5) + d.key("home", pause=0.0) + capture.settle(quiet=0.5) + d.camera.mark("poster") + d.hold(2.6) + d.subtitle("and talk to its\n*command line*") + d.key("end", pause=0.5) + d.walk_to("Command line", "up") + d.hold(0.4) + d.key("enter", pause=0.0) + capture.settle(quiet=0.8) + d.hold(0.6) + d.type("neighbors") + d.hold(0.4) + d.key("enter", pause=0.0) + capture.settle(quiet=1.2, timeout=30) + d.hold(3.4) + + +def tx_optimize(d: Director) -> None: + """TX optimize: a login, a sweep of the TX power of Rosemont, and the best power set.""" + from meshterm.core import preferences + from meshterm.demo import world + + capture = d.capture + d.open_page("tx opt", "node to tune") + d.start("Tune a repeater's\n*TX power*") + d.hold(1.4) + d.type("rose") + d.hold(0.4) + d.key("enter", pause=0.0) + d.wait_for("measure at") + d.hold(0.8) + d.type("mont-r") + d.hold(0.4) + d.key("enter", pause=0.0) + d.wait_for("TX optimize — Rosemont → Mont-Royal") + d.hold(1.6) + d.key("enter", pause=0.0) # Sweep + d.wait_for("Admin password for Rosemont") + d.subtitle("Log in to it\n*over the air*") + d.hold(0.8) + d.type(world.ADMIN_PASSWORD) + d.hold(0.4) + d.key("enter", pause=0.0) + d.subtitle("MeshTerm tries each power,\nand *measures* it") + d.hold(3.0) + # The sweep is up to 30 traces, with the transmit cooldown between two of them. Off + # camera, a short cooldown makes the run shorter, and the video does not show it. + with d.off_camera(): + cooldown = preferences.current().trace_cooldown_s + preferences.current().set("trace_cooldown_s", 0.2) + try: + d.wait_for("Apply winner", timeout=300) + finally: + preferences.current().set("trace_cooldown_s", cooldown) + capture.settle(quiet=0.5) + d.subtitle("then finds the *best* one") + d.camera.mark("poster") + d.hold(3.0) + d.key("enter", pause=0.0) # Apply + d.wait_for("set on Rosemont") + d.subtitle("and sets it\nwith *one key*") + d.hold(3.0) + + +# --------------------------------------------------------------------------- This app + + +def preferences(d: Director) -> None: + """Preferences: how MeshTerm behaves, and a staged change.""" + d.open_page("prefer", "Preferences") + d.start("Make MeshTerm\nwork *your way*") + d.camera.mark("poster") + d.hold(2.6) + d.walk_to("Transmit cooldown", "down", pause=0.3) + d.hold(0.5) + d.key("enter", pause=0.0) + d.wait_for("Allowed:") + d.hold(0.8) + for _ in range(4): + d.key("backspace", pause=0.15) + d.type("3") + d.hold(0.6) + d.key("enter", pause=0.0) + d.subtitle("Each change waits\nuntil you *apply* it") + d.hold(1.2) + d.key("end", pause=0.0) + d.wait_for("staged change") + d.hold(3.0) + + +def diagnostics(d: Director) -> None: + """Diagnostics: everything a bug report needs.""" + d.open_page("diagn", "MeshTerm diagnostics") + d.start("Everything a *bug report*\nneeds, on one page") + d.camera.mark("poster") + d.hold(3.4) + # Only a few lines down, to the facts of the radio: the next section shows the folders + # of the machine that made the video. + for _ in range(5): + d.key("down", pause=0.3) + d.hold(2.6) + + +REELS: dict[str, Reel] = { + "chat": Reel( + "Chat", + chat, + _caption( + "Off-grid chat over LoRa radio, right in your terminal.", + "Chat on channels, in direct messages, and in rooms. See every path a message" + " took across the mesh. Mention a friend, and their name turns into a tag. Turn" + " any link into a QR code for your phone.", + ), + ), + "channels": Reel( + "Channels", + channels, + _caption( + "All your MeshCore channels, with their activity at a glance.", + "Share a channel with a QR code, and keep a channel's messages in one region.", + ), + ), + "rooms": Reel( + "Rooms", + rooms, + _caption( + "The message boards of the mesh, in your terminal.", + "Join a room server, read every post, also the ones you missed while you were" + " away, and post to it. A ✓ tells you that the room got your post.", + ), + ), + "courier": Reel( + "Courier", + courier, + _caption( + "Write now. Deliver later.", + "The courier keeps a message in its outbox until the contact is heard again, or" + " until the time you pick. Then it sends it for you.", + ), + ), + "contacts": Reel( + "Contacts", + contacts, + _caption( + "Every node you know, sorted your way.", + "Each node has its own page, with a map, its signal, and every route between you" + " and it.", + ), + ), + "dashboard": Reel( + "Dashboard", + dashboard, + _caption( + "Your whole mesh, live, on one screen.", + "Activity, every kind of packet, and the health of your radio. Narrow it to one" + " region with one key.", + ), + background=True, + ), + "livefeed": Reel( + "Live feed", + livefeed, + _caption( + "Every packet your radio hears, the moment it arrives.", + "Open one to see what it is, where it came from, and the repeaters that carried it.", + ), + background=True, + ), + "watchtower": Reel( + "Watchtower", + watchtower, + _caption( + "Know when a node goes quiet.", + "The watchtower watches the nodes you pick. It tells you when one goes silent," + " when it comes back, and when a new node shows up on the mesh.", + ), + ), + "timemachine": Reel( + "Time machine", + timemachine, + _caption( + "Everything your radio has ever heard.", + "MeshTerm keeps a record of every packet. Explore your mesh day by day and hour" + " by hour, and the story of each node.", + ), + ), + "map": Reel( + "Map", + map_, + _caption( + "Every node of your mesh on a real street map, in your terminal.", + "Type a name to find a node, and zoom in down to the streets. The map comes from" + " OpenStreetMap.", + ), + ), + "walk": Reel( + "Mesh walk", + walk, + _caption( + "Walk the mesh, one link at a time.", + "Start from your own node, and see who each repeater hears, and how well.", + ), + ), + "trace": Reel( + "Trace target", + trace, + _caption( + "Trace a route to any repeater.", + "See the signal at every hop of the way there and back. Each new record goes to" + " your trophy case.", + ), + ), + "tracepath": Reel( + "Trace path", + tracepath, + _caption( + "Build a route hop by hop, then trace it.", + "MeshTerm suggests the strongest next hop from what it has heard.", + ), + ), + "records": Reel( + "Trophy case", + records, + _caption( + "Every trace is scored.", + "Your longest, farthest, and widest walks across the mesh, with their route and" + " the area that they covered.", + ), + ), + "info": Reel( + "Device info", + info, + _caption( + "Your radio's status at a glance.", + "Battery, airtime, packets, and every setting, with what it does.", + ), + ), + "config": Reel( + "Device config", + config, + _caption( + "Change your radio's settings.", + "Set your location on a map. Nothing changes on the radio until you apply it.", + ), + ), + "advert": Reel( + "Send advert", + advert, + _caption( + "Announce your node to the mesh.", + "Or share it as a QR code that a phone can scan.", + ), + ), + "repeater-admin": Reel( + "Repeater admin", + repeater_admin, + _caption( + "Run a repeater over the air.", + "Read and change its settings, and talk to its command line, from your terminal.", + ), + ), + "tx-optimize": Reel( + "TX optimize", + tx_optimize, + _caption( + "Tune a repeater's TX power for the best signal.", + "MeshTerm logs in to the repeater over the air, tries each power level, measures" + " how well the target hears it, and sets the best one. Often, that is a lower" + " power.", + ), + ), + "preferences": Reel( + "Preferences", + preferences, + _caption( + "Make MeshTerm work your way.", + "Each preference says what it does, and each change waits until you apply it.", + ), + ), + "diagnostics": Reel( + "Diagnostics", + diagnostics, + _caption( + "Everything a bug report needs, on one page.", + "The version, the computer, the terminal, and the radio.", + ), + ), +} diff --git a/scripts/reels.py b/scripts/reels.py index a520fba..3c7dc09 100644 --- a/scripts/reels.py +++ b/scripts/reels.py @@ -1,12 +1,14 @@ # SPDX-License-Identifier: Apache-2.0 """Make the videos of MeshTerm for Instagram from the demo mesh. - python scripts/reels.py NAME [--out DIR] [--recording FILE] + python scripts/reels.py NAME ... [--out DIR] [--recordings DIR] + python scripts/reels.py all [--out DIR] [--recordings DIR] -Each video shows one feature of MeshTerm. ``NAME`` is one of :data:`REELS`. The video is -a Reel: a vertical video of 1080×1920 pixels (9:16), at 30 video frames each second. It -has subtitles in the picture and no sound. Many people watch Instagram with the sound -off, and Instagram cannot show a subtitle file on a Reel. +Each video shows one page of MeshTerm. ``NAME`` is a key of ``reel_tours.REELS``, where +the tours are, and ``all`` makes each video, one after the other. The video is a Reel: a +vertical video of 1080×1920 pixels (9:16), at 30 video frames each second. It has +subtitles in the picture and no sound. Many people watch Instagram with the sound off, +and Instagram cannot show a subtitle file on a Reel. The script runs MeshTerm with ``--demo`` in this process, as ``scripts/video.py`` does. The terminal has 72 columns, the narrowest terminal where each screen of the regular @@ -16,11 +18,12 @@ under it are the subtitles. The bottom of the video stays empty, because Instagr the name of the account and the caption of the post there. The video ends on a card with the wordmark and the address of the website. -The demo device plays no background traffic. Thus the screen does not change while the -tour waits off camera for a live message, and the cut does not show. +The demo device plays no background traffic, except for a page that shows the traffic +(``Reel.background``). Thus the screen does not change while the tour waits off camera +for a live message, and the cut does not show. -The script writes three files into ``DIR`` (by default ``output/reels``, which git does -not track): +For each video, the script writes three files into ``DIR`` (by default ``output/reels``, +which git does not track): * ``NAME.mp4``: the video, H.264 High in ``yuv420p``, with its ``moov`` box at the start. It has a silent AAC track: the track costs almost nothing, and some apps that @@ -29,6 +32,10 @@ not track): centre, at 3:4. * ``NAME.txt``: a caption for the post. +With ``--recordings``, the script keeps the recording of each video in that folder +(``NAME.pickle``). When the file exists, a later run paints and encodes it again, and does +not run MeshTerm. Never keep a recording across a change to the app. + What it needs: the needs of ``scripts/video.py``, but not the website checkout. """ @@ -42,11 +49,11 @@ import tempfile import time from collections.abc import Callable, Iterable from concurrent.futures import ProcessPoolExecutor -from dataclasses import dataclass from pathlib import Path import screenshots import video +from reel_tours import REELS, Reel from screenshots import ROOT, Capture FPS = video.FPS @@ -94,57 +101,89 @@ Cue = tuple[int, str | None] def main(argv: list[str]) -> int: - """Record the tour of one video in a child process, then paint and encode it.""" + """Make each video that ``argv`` names, one after the other. + + Returns: + 0 if each video was made, 1 if one or more failed. A failure does not stop the + videos after it. + """ parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) - parser.add_argument("name", choices=sorted(REELS)) + parser.add_argument("names", nargs="+", metavar="NAME", help=f"all, or: {', '.join(REELS)}") parser.add_argument("--out", type=Path, default=ROOT / "output" / "reels") parser.add_argument( - "--recording", + "--recordings", type=Path, - help="keep the recording in this file. If the file exists, use it and do not run MeshTerm", + help="keep each recording in this folder. If it has one, use it and do not run MeshTerm", ) parser.add_argument("--child", type=Path, help=argparse.SUPPRESS) args = parser.parse_args(argv) - reel = REELS[args.name] + names = list(REELS) if args.names == ["all"] else args.names + unknown = [name for name in names if name not in REELS] + if unknown: + parser.error(f"no video named {', '.join(unknown)}") if args.child: + reel = REELS[names[0]] video._watch_live_start() return screenshots.run_demo( "terminal", lambda capture, keys: _record(capture, keys, reel, args.child), - background=False, + background=reel.background, grid=GRID, ) args.out.mkdir(parents=True, exist_ok=True) + if args.recordings: + args.recordings.mkdir(parents=True, exist_ok=True) + failed = [name for name in names if not _make(name, args.out, args.recordings)] + if failed: + print(f"failed: {', '.join(failed)}", flush=True) + return 1 if failed else 0 + + +def _make(name: str, out: Path, recordings: Path | None) -> bool: + """Record the tour of one video in a child process, then paint and encode it. + + Returns: + Whether the video was made. + """ + reel = REELS[name] with tempfile.TemporaryDirectory(prefix="meshterm-reel-") as work: - recording = args.recording or Path(work) / "recording.pickle" + recording = (recordings or Path(work)) / f"{name}.pickle" if not recording.exists(): - print(f"recording the tour of {args.name}...", flush=True) + print(f"{name}: recording the tour...", flush=True) home = Path(tempfile.gettempdir()) / "meshterm-reels" done = subprocess.run( - [sys.executable, __file__, args.name, "--child", str(recording)], - env=screenshots.child_env(home), + [sys.executable, __file__, name, "--child", str(recording)], + # The size of the terminal for what reads it from the environment, such as + # Diagnostics (shutil.get_terminal_size). The process has no terminal. + env={ + **screenshots.child_env(home), + "COLUMNS": str(GRID[0]), + "LINES": str(GRID[1]), + }, check=False, ) if done.returncode or not recording.exists(): - print(f"the recording failed ({done.returncode})", flush=True) - return 1 + print(f"{name}: the recording failed ({done.returncode})", flush=True) + return False tape = pickle.loads(recording.read_bytes()) states = _states(tape["frames"], tape["cues"]) - print(f"painting {len(set(states))} images for {len(states) / FPS:.1f} s...", flush=True) + print( + f"{name}: painting {len(set(states))} images for {len(states) / FPS:.1f} s...", + flush=True, + ) images = _paint(reel.title, tape["grids"], tape["cues"], states, Path(work)) - target = args.out / f"{args.name}.mp4" - print("encoding...", flush=True) + target = out / f"{name}.mp4" _encode([images[state] for state in states], Path(work), target) frames = tape["frames"] mark = tape["marks"].get("poster", len(frames) // 2) poster = tape["grids"][frames[min(mark, len(frames) - 1)]] - cover = args.out / f"{args.name}-cover.png" + cover = out / f"{name}-cover.png" Composer(reel.title).frame(poster, (tape["cues"][0][1], 1.0, True)).save(cover) - caption = args.out / f"{args.name}.txt" + caption = out / f"{name}.txt" caption.write_text(reel.caption, encoding="utf-8") for path in (target, cover, caption): print(f"{path} ({path.stat().st_size // 1024} KB)", flush=True) - return 0 + return True # --------------------------------------------------------------------------- the child @@ -162,6 +201,49 @@ class Director(video.Presenter): """Show ``text`` from the next video frame (refer to :data:`Cue`).""" self.cues.append((len(self.camera.frames), text)) + def open_page( + self, name: str, wait: str, *, settle: float = 0.8, timeout: float = 30.0 + ) -> None: + """Open a page from the main menu, off camera: type ``name`` to filter, then Enter. + + Args: + name: The start of the name of the page in the menu. + wait: A text that the page shows when it is open. + settle: How long the screen must stay the same before the tour goes on. + timeout: How long to wait for the page (the map loads its tiles). + """ + self.capture.wait_for("Chat", timeout=60) + self.capture.settle(quiet=0.5) + self.type(name) + self.key("enter") + self.wait_for(wait, timeout=timeout) + self.capture.settle(quiet=settle, timeout=timeout) + + def start(self, text: str) -> None: + """Show the first subtitle, and roll the camera.""" + self.subtitle(text) + self.camera.roll() + + def count(self, text: str) -> int: + """How many times ``text`` is on the screen now.""" + with self.capture.lock: + return self.capture.terminal.text().count(text) + + def wait_until_shows(self, test: Callable[[], bool], timeout: float = 30.0) -> None: + """Wait until ``test`` is true. + + Raises: + TimeoutError: The test stayed false. + """ + start = time.monotonic() + while time.monotonic() - start < timeout: + if test(): + return + time.sleep(0.1) + with self.capture.lock: + screen = self.capture.terminal.text() + raise TimeoutError(f"the screen did not change as expected. The screen:\n{screen}") + def walk_to(self, label: str, key: str = "up", tries: int = 16, pause: float = 0.22) -> None: """Press ``key`` at a steady pace until the highlight is on the line of ``label``. @@ -193,82 +275,6 @@ def _record(capture: Capture, type_text: Callable[[str], None], reel: Reel, path print(f"recorded {len(camera.frames) / FPS:.1f} s, {len(camera.grids)} screens", flush=True) -def _chat(d: Director) -> None: - """The chat: the conversations, a live message, the paths, a mention, and a QR code.""" - from meshterm.demo import script - - capture = d.capture - capture.wait_for("Chat", timeout=60) - capture.settle(quiet=0.5) - # The video starts on the list of the conversations. The main menu is not in it. - d.type("chat") - d.key("enter") - d.wait_for("pick a conversation") - capture.settle(quiet=0.8) - - print("the conversations", flush=True) - d.subtitle("Off-grid chat over *LoRa radio*,\nright in your terminal") - d.camera.roll() - d.hold(2.8) - d.type("pub") - d.hold(0.5) - d.key("enter", pause=0.0) - d.wait_for(screenshots.PATHS_MESSAGE[2]) - d.subtitle("Everyone gets\ntheir own *colour*") - d.hold(2.6) - - print("a live message", flush=True) - offset, _, line = next(item for item in script.LIVE_CHANNEL if item[1] == "Public") - with d.off_camera(): - d.wait_until(video._start() + offset - 0.8) - d.wait_for(line.text, timeout=20) - d.subtitle("New messages arrive *live*,\nover the air") - d.hold(2.4) - - print("the paths of a message", flush=True) - for _ in range(3): # Chloé, Félix, then Gabriel - d.key("up", pause=0.45) - d.hold(0.5) - # A key press can be lost while the transcript draws. The camera does not show the - # tries: it shows the dialog of the right message as it opens. - with d.off_camera(): - video._open_paths(d) - d.subtitle("See *every path* a message\ntook to reach you") - d.hold(2.2) - d.key("down", pause=1.4) - d.key("up", pause=1.4) - d.key("down", pause=0.5) - d.camera.mark("poster") - d.hold(1.6) - d.key("escape") - d.key("escape") # the first Esc closes the dialog, the second clears the selection - - print("a mention, and its answer", flush=True) - d.subtitle("*Mentions* turn into\nname tags as you type") - d.hold(0.6) - # The mention is typed in full: the ] makes it a chip. - d.type("Hey @[Dave-Lachine], are you coming Saturday?") - d.hold(0.8) - d.key("enter", pause=0.0) - sent = time.monotonic() - d.wait_for("0/130") # the compose line is empty: the message went - d.hold(0.8) - # Dave answers after ``script.REPLY_DELAY_S``. The camera does not show most of the wait. - with d.off_camera(): - d.wait_until(sent + script.REPLY_DELAY_S - 0.6) - d.wait_for("be there at 2", timeout=30) - d.subtitle("When someone *mentions you*,\nyou get a ★") - d.hold(2.8) - - print("a link as a QR code", flush=True) - d.subtitle("Turn any link into a\n*QR code* for your phone") - d.hold(0.4) - d.walk_to("11:04") # our message with the link to the map - d.hold(0.7) - d.key(text="u", ctrl=True, pause=0.0) - d.hold(3.4) - - # --------------------------------------------------------------------------- the video #: The state of one video frame: the copy of the screen and the subtitle, or the end card. @@ -542,43 +548,5 @@ def _encode(images: list[Path], work: Path, target: Path) -> None: subprocess.run(command, check=True) -# --------------------------------------------------------------------------- the reels - - -@dataclass(frozen=True) -class Reel: - """One video of the series. - - Attributes: - title: The name of the feature, in the series line above the terminal. - tour: The keys of the tour, and the subtitles. - caption: The text of the post on Instagram. - """ - - title: str - tour: Callable[[Director], None] - caption: str - - -REELS: dict[str, Reel] = { - "chat": Reel( - "Chat", - _chat, - "Off-grid chat over LoRa radio, right in your terminal.\n" - "\n" - "MeshTerm is a free, open-source MeshCore client for Windows, macOS, and Linux. " - "Chat on channels, in direct messages, and in rooms. See every path a message took " - "across the mesh. Mention a friend, and their name turns into a tag. Turn any link " - "into a QR code for your phone.\n" - "\n" - "Filmed in MeshTerm's demo mesh over Montréal (meshterm --demo).\n" - "\n" - "meshterm.net\n" - "\n" - "#MeshCore #LoRa #OffGrid #MeshNetwork #Terminal #TUI #OpenSource\n", - ), -} - - if __name__ == "__main__": sys.exit(main(sys.argv[1:]))