My graduation project. An interactive terminal learning platform that provides guided courses, visual file tree functionality, and error message guidance. Each course creates a container on the server side for user interaction.

Stack: TypeScript, Vue, Express, WebSocket, Docker in Docker
License: GPL

GitHub

2024 - 2025

Multichannel video synchronization tool that works across devices and platforms, with mobile support.

Video: Lin Pei-Yao. Triangular Relationship / Three-Channel Loop Video / 03'39" / 2021

Background

Multichannel video playing is a common needs in modern art exhibitions. The usual way to implement it is using dual monitors connected to the same computer, and use proprietary video player to control it.

However, this method requires different monitors to be physically connected, and doesn’t allow using mobile devices as display.

Therefore, I developed a Web-based system to allow multidevice multichannel video synchronisation.

Structure

The system consists of two parts: Server and Client

• Server
  • NodeJS, TypeScript, Electron, tRPC, Express, Socket.io
  • Store the video files
  • Manage the current playhead
  • Calculate the latency to each connected client
  • Periodically update current playhead to every client via WebSocket
  • Provide a tRPC and RESTful interface for control
  • Wrapped inside an Electron desktop application to simplify starting.
• Clients
  • TypeScript, ReactJS, Vite, tRPC, Socket.io, Redux
  • Connect to the server instance, load available videos
  • Dynamically syncing current playhead to the remote
  • Provide Admin interface when open inside Electron

Easy-to-Use Interface

Admin Interface of Synchan

In an art exhibition environment, the exhibition managers usually are not from tech background. It is required to provide an easy-to-use interface to start the whole system. Also, the installations usually don’t have mouse and keyboard connected once the set-up is completed. Thus, the unattended start-up is important to minimise the effort for the exhibition managers.

There are many limitations for a Web-based application to achieve this. Modern browsers require user interaction to play the sound, auto full-screen is also blocked.

Therefore, I wrapped the backend and the admin interface as an Electron application. The server is spawned once the application starts, requiring no terminal or background service configuration. Furthermore, Electron can be configured to allow autoplay and open-to-fullscreen. The application also memorises last played video, and automatically play it on the start.

As a result, exhibition managers can just turn on the computer, and the whole installation is up and running.

Real-Time Sync Engine

Latency between devices is the biggest problem for cross-device synchronisation, especially when both have audio tracks, the difference becomes trivial.

The latency mainly comes from the network latency between server and clients, while different clients have different latency. In the time code synchronisation protocol, I implemented a round-trip latency measurement. Every time the server sends a new time code, it starts a stopwatch, and wait for client’s ping back. Then server uses a moving-window algorithm to calculate the median of recent transmissions, so the spikes in networking can be eliminated. Finally server includes the calculated latency in the next time code packet sent to the client.

Once the client receives the time code with latency, it can calculate the real time code. But the next problem arises:

The video seek operation in the browser takes long time (>0.5s) on low-end devices like Raspberry Pi. So it is not possible to do precise control using seek, and it also breaks the continuity of the video playback.

Therefore, I use micro speed adjustment to align the target playhead, by a linear speed control between 1.05x to 0.95x. The number chosen is a balance between adjustment balance and user experience. It is unnoticeable by the users, and it doesn’t breaks the video playing or lag the browser.

After the fix, latency can be minimised to under 5ms, which is indistinguishable by human ear.

Performance Optimisation via Preloading

The networking may not be stable in an exhibition environment. While playing on low-end devices like Raspberry Pi, mid-playback buffering often causes little lags. Besides, exhibition installations usually play the same videos, and the set-up time is before the exhibition starts, which can be ignored.

Therefore, instead of streaming, it has many benefits to preload the whole video before playing.

I implemented a cache layer in the video player, which downloads the whole file and saves into IndexedDB. This method works in every modern browser out-of-box.

By using preloading, it solves the mid-playback buffering issue and significantly improves the stability.

Cross-Platform Clients

Synchan itself ships a Web-based client, which can run on every platform with a modern browser, including both desktop and mobile devices. Its server-client structure also allows it to be used by different clients.

On low-end devices like Raspberry Pi, running a Chromium instance to play video may be too heavy. Thus, I developed a headless client VLChan using VLC Python SDK. It connects to a Synchan Server and plays local files with synchronised playhead, allows best performance on a Raspberry Pi.

Show Cases

Lin Pei-Yao Solo Exhibition: The Dual Double-Channel (2024)

Used in work Gaze Triangle

• 3 video channels + 2 audio channels
• Server: Raspberry Pi 4
• Clients
  • Raspberry Pi 4 (same machine, connected monitor)
  • Mac Mini (projector + Bluetooth headset)
  • Android Phone (play audio by built-in speaker)

Lin Pei-Yao Solo Exhibition: Who is the speaker? (2025)

Used in work Inter-view with a Philosopher

• 1 video + 2 audio channels
• Server: Mac Mini
• Clients
  • Mac Mini (same machine): Video + audio
  • Raspberry Pi 4 (audio only VLC client)
• Extra time-code control with Actionwire

Want to Try?

Currently available by invitation only. For inquiries, please contact wancat@wancat.cc

This project is developed specific for Lin Pei-Yao Solo Exhibition: Who is the speaker? (2025).

In this exhibition, it required speech recognition for selected keywords, and perform specific actions, including smart light control and video playhead control. The speech recognition is done in real-time, deployed locally on a Raspberry Pi.

For example, in the command “Drink Tea”, it blinks one set of lights and seeks the video to a specific time (00:25) and jumps back to original position after 10 seconds.

Different voice commands have different actions, and some of them may depends on each other.

To make the concurrent events manageable, I used Reactive Programming design pattern via RxPy.

Structure

The program is divided into three parts: Events, Commands, and Actions.

Events are the input to the system, including microphone and WebSocket inputs. It will be transform into an Observable stream.

Actions are the output behaviours. Including light control and video playhead control.

Commands are the business logic. Freely connecting, composing, mixing all the inputs, and producing one output. Can be easily customised by user needs.

• Events (inputs)
  • Microphone -> Vosk -> Keyword extraction
  • WebSocket -> Current timecode
• Commands
  • Define the pipeline logic for every command
  • Written in Reactive Programming styles
  • No hidden state management. Easy to update
• Actions (outputs)
  • Light control -> LIFX LAN API
  • Video playhead control -> HTTP request

Keywords Recognition

I used Vosk as the offline speech recognition model, because it is small enough to run on a Raspberry Pi.

The original accuracy of the model is not good, and it is designed as a speech-to-text model, not for recognise specific keywords. I customised the vocabulary list to make it only select tokens that appears the keyword list. It’s also important to include [unk] in the list, to prevent the model output unknown words.

Synchan Integration

The video playing system is Synchan, a multichannel multidevice synchronised video playing system. It allows control via HTTP requests, and it updates the current time code to every clients via WebSocket. The time code is parsed as an Observable stream, and used to perform action according to video time code.

For example, in the beginning of the video, it turns on the light in the exhibition as the light is turned on in the video. And in the command “Drink Tea”, it seeks the video to back to 00:25, where the performer asked “Would you like some tea?”, and seeks back to the original playhead after 10 seconds.

Tech Stack

• Python
• RxPy
• Vosk
• Socket.IO
• lifxlan: Smart Light Control in LAN

Gallery

Want to Try?

Currently available by invitation only. For inquiries, please contact wancat@wancat.cc

I came across an article published in 2019 by independent research lab Ink & Switch titled “Local-first software: You own your data, in spite of the cloud”. After reading it, I was deeply moved and inspired. Here I’ll share a brief summary and my thoughts.

Looking at the modern software ecosystem, you’ll notice it’s completely different from ten years ago. Instead of applications installed on your computer, more and more software is delivered as web services. Most of our computer time is now spent inside a browser.

Over the past decade or so, the software industry has undergone a paradigm shift—from traditional desktop software to web services. This brought better cross-platform support, instant access without installation, and seamless cross-device experiences. Most importantly, it made real-time multi-user collaboration possible.

Iconic examples include how Microsoft Word, PowerPoint, and Adobe Illustrator are gradually being replaced by Google Docs, Canvas, and Figma. These services support real-time collaboration, saving the mental overhead of emailing files back and forth. More importantly, they allow multiple people to edit simultaneously without conflicts.

However, the shift from desktop software to web services has also introduced the following problems:

1. Speed: Every operation needs to interact with a remote data center. Even checking a box requires waiting for network latency.

2. Network dependency: Whether it’s your data or the software that manipulates it, the only “source of truth” is stored in a remote data center. When you lose network connection or the server goes down, you can’t continue working.

3. Loss of ownership: You no longer own your files—you just have credentials that grant access to them, and the service provider can revoke that access at any time.

Here’s an insightful summary from the article:

The cloud gives us collaboration, but old-fashioned apps give us ownership. Can’t we have the best of both worlds?

Software that achieves this is what the article proposes as local-first software.

Seven Ideals of Local-First

The article defines local-first as: prioritizing local storage and local networks, giving users complete ownership while still enjoying the user experience of cloud services.

It proposes seven specific ideals:

1. Speed: Your data is on your device, all operations complete instantly, syncing with other devices in the background.

2. Multi-device: Your data should be accessible and editable across multiple devices.

3. Offline functionality: When the network is unavailable, you should still have full access to single-device functionality.

4. Real-time collaboration: Ability to work simultaneously with others while avoiding or resolving conflicts.

5. Longevity: If the company goes out of business, can users still open their data? After 100 years, will this data still be readable?

6. Security and privacy: User data should default to existing only on the user’s own devices, avoiding the surveillance, hacking, and data misuse issues that come with centralized servers.

7. Ownership: Do you fully own your data? If your account is suspended by the company or a court, can you still use it?

Below is an excerpt from the article’s evaluation of existing software, services, and technologies against these seven ideals:

✓ Good — Partial ✗ Bad

• Files + email / cloud sync: Actually works quite well. You have complete file ownership and smooth operation on your own computer. The only issue is that when collaborating with others, you need to send files back and forth and constantly rename them (report_1.docs, report_2.docx, report_final_4.docx).
  Cloud sync somewhat solves the file-sending hassle, but when the same file is modified in two places simultaneously, resolving conflicts becomes very difficult.

• Google Docs / typical web apps: Cross-device usage and multi-user collaboration are possible, but without internet, you can’t do anything. You also need to worry about losing your work due to account suspension or other reasons.

• Most mobile apps: Although they’re programs downloaded to your phone, most features rely on server functionality. Without internet, you can’t even open videos you posted yourself.

• Git+GitHub: Git is the go-to tool for managing code versions and multi-user collaboration in the software industry. It perfectly meets the needs of software development. However, it’s primarily designed for plain text files (code) and has a steep learning curve for everyday use by ordinary people.

  But its design—especially how each endpoint has complete data and how it uses edit history for conflict comparison and recovery—is very worth learning from.

What technology can meet all seven of these conditions? In the article, the lab team discovered a promising foundational technology: Conflict-free Replicated Data Types (CRDTs).

Understanding CRDTs

CRDTs were proposed in 2011 in a computer science journal. It’s a data structure that enables multiple computers to collaborate while automatically resolving conflicts. CRDTs don’t just store the final state of data—they also preserve the complete change history, and by replaying the history, you can arrive at the same final state.

Taking text editing as an example, suppose the original string is:

1234567890

A inserts a 0 after 3:

1230456789

B (from the original string) removes 8:

12345679

When the computer tries to merge these two operations, it finds that none of the characters after 123 match up. Traditionally, we’d use more advanced string comparison algorithms to resolve this, but if we know the modification history, we just need to apply each change to get the conflict-resolved result:

123456789   -> original string
1230456789  -> insert 0 after 3
123045679   -> remove 8

If there’s a conflict that truly can’t be automatically resolved, CRDTs can also provide more accurate and localized comparison information for the application or user to resolve.

This simple case might not show the value clearly, but anyone who has used cloud file sync knows how troublesome and tricky it is when two computers modify the same file. Comparison based solely on results is difficult, which is why simple file/state synchronization can’t implement local-first.

Therefore, with CRDTs as the foundation, we can solve cross-device data conflict issues and develop systems that can both operate offline and collaborate with others.

Case Study: Heptabase

Heptabase is a subscription-based note-taking and knowledge base software founded by Taiwanese, dedicated to helping anyone make sense of complex topics. I’ve been using it for a year and a half and absolutely love it. It has profoundly changed how I learn and helped me build a more sustainable and deep knowledge system.

What I enjoy most about using Heptabase is its smooth user experience—each device can operate independently, cross-device syncing doesn’t create conflicts, and this year they added real-time multi-user collaboration.

I used to use Notion but couldn’t stand the long loading times every time I opened it. Later I returned to the embrace of plain text markdown, syncing markdown files with Nextcloud. However, the tree structure of computer files isn’t suitable for building complex knowledge systems. It wasn’t until I discovered Heptabase that I found a tool that truly fit my needs.

It was also while researching how to develop such systems, using Heptabase’s architecture as a prototype, that I discovered the local-first concept. I’m not sure if this was one of their original design philosophies, but in my experience using it, it satisfies many of these ideals.

Below I evaluate Heptabase using the seven local-first ideals:

✓ Good — Partial ✗ Bad

1. ✓ Speed: Complete data locally, opens immediately (under 2 seconds)

2. ✓ Multi-device: Works across computers, phones, tablets, and web

3. ✓ Offline functionality: Still able to fully access and modify all data offline, including writing cards and editing whiteboards

4. ✓ Real-time collaboration: Supports simultaneous editing of the same whiteboard with others

5. — Longevity: Heptabase is proprietary subscription software—you can’t use it without paying. However, data is backed up daily on your own device in markdown and JSON formats, so it can still be parsed with other software.

6. — Security and privacy: Heptabase maintains a copy of your data on servers to facilitate syncing, and currently doesn’t offer end-to-end encryption.Users can choose not to enable syncing, but then can’t enjoy cross-device functionality. This option was removed in a recent update (v1.75.8).

7. — Ownership: Users have all data in markdown and JSON, but without the Heptabase software itself, it’s not as easy to use—though technically it can be parsed yourself.

Overall, Heptabase demonstrates how local-first architecture can be implemented in a product with excellent user experience and make it one of the product’s core selling points.

The Coming of the Next Era

The internet went from one-way transmission in web1 to user-generated content in web2, and now to the web3 movement that returns ownership to users. However, application development still predominantly uses server-centric web apps.

The local-first and CRDTs architecture can add multi-user collaboration and cross-device functionality while preserving user sovereignty. Whether it’s family photo albums, notes, expense tracking, or fitness logs, everything can be collaborated on with others in a more private and secure way. Such applications are like app3—they will be the application development paradigm of the future generation.

References

• Martin Kleppmann, Adam Wiggins, Peter van Hardenberg, Mark McGranaghan. (April 2019). Local-first software. You own your data, in spite of the cloud. Ink & Switch. https://www.inkandswitch.com/essay/local-first/
• Marc Shapiro, Nuno Preguiça, Carlos Baquero, Marek Zawirski. (2011). Conflict-free Replicated Data Types. French Institute for Research in Computer Science and Automation. https://pages.lip6.fr/Marc.Shapiro/papers/RR-7687.pdf

But when it comes to generating reports, it often takes me time to figure out all the commands I need. Also, having a way to archive previous data is important. I used to write a shell script with all the report commands, and add a lot of echo statements to generate a markdown report. However, this approach is hard to read and makes the template difficult to maintain.

That’s why I made mdsh, a markdown template engine written in Go, which allows you to execute shell scripts within Markdown. It allows you to use Go’s template syntax in markdown, and puts the execution results in the generated output.

You can download it from the release page. Once you downloaded ant decompressed it, you can put the mdsh binary to some place in your $PATH. On Linux, for example, you can put it under /usr/loca/bin via:

sudo cp mdsh /usr/local/bin

You can also install it with Go CLI:

go install github.com/lancatlin/mdsh@latest

This will put it into $GOPATH/bin (usually $HOME/go/bin)

The First Template

Suppose we want to generate a system information report. You can define a markdown template system-info.md as follows:

# 💥 System Information Report for {{ sh "hostname" }}

* **Hostname**: {{ sh "hostname" }}
* **Username**: {{ sh "whoami" }}
* **Uptime**: {{ sh "uptime -p" }}
* **System**: {{ sh "uname -a" }}
* **CPU**: {{ sh "uname -m" }} — {{ sh "nproc" }} cores
* **IP Address**: {{ sh "hostname -I || ip a | grep inet" }}
* **Default Gateway**: {{ sh "ip route | grep default || netstat -rn | grep default" }}

Run the template:

mdsh system-info.md

It will render into:

# 💥 System Information Report for `fedora`

* **Hostname**: `fedora`
* **Username**: `wancat`
* **Uptime**: `up 1 hour, 13 minutes`
* **System**: `Linux fedora 6.15.6-200.fc42.x86_64 #1 SMP PREEMPT_DYNAMIC Thu Jul 10 15:22:32 UTC 2025 x86_64 GNU/Linux`
* **CPU**: `x86_64` — `16` cores
* **IP Address**: `172.26.198.115 2405:dc00:ec83:ec80:af9c:87ed:9bae:bd0d`
* **Default Gateway**: `default via 172.26.198.50 dev wlp1s0 proto dhcp src 172.26.198.115 metric 600`

It makes generating reports as easy as a breeze.

Different Template Functions

Currently, it supports 3 types of template functions, which change the format they generate to:

1. sh: puts the output in inline code
2. shell: puts the output in a

code block

3. raw: puts output without any decorations

Also, any functions and syntax supported in text/template are supported.

Custom Parameters from Command Line Arguments

The best part of mdsh is that it supports custom parameters, which means you can define the parameters you’re going to use in the template, and pass them through command line arguments.

You can access the parameters through both template data and environment variables. So you can access these variables from the script with ease.

For example, I need to generate a monthly report for my ledger. I need to specify begin and end times for the report.

Define the template as follows:

---
params:
  b:
    required: true
  e:
    required: true
  f:
    default: examples/ledger.j
---
// The template body

As you can see in the code, you can define custom parameters in the params: section in the frontmatter. I defined 3 parameters: b, e, and f, which stand for begin, end, and file. (This follows the convention in hledger)

Then I can use those parameters in the template body.

# Finance Report from {{.b}} to {{.e}}

## Net Income:

{{ shell "hledger -f $f income -b $b -e $e --monthly" }}

I use {{ .b }} to access the parameter directly and put it in the heading. Then I can use $b in the command. All the parameters will be passed as environment variables to the executing shell. So you can access them very easily.

mdsh hledger_monthly.md -b 2011-01 -e 2011-02

# Finance Report from 2011-01 to 2011-02

## Net Income:

```
Income Statement 2011-01

                         ||        Jan
=========================++============
 Revenues                ||
-------------------------++------------
 Income:Salary           ||  $2,000.00
-------------------------++------------
                         ||  $2,000.00
=========================++============
 Expenses                ||
-------------------------++------------
 Expenses:Auto           ||  $5,500.00
 Expenses:Books          ||     $20.00
 Expenses:Food:Groceries ||    $109.00
-------------------------++------------
                         ||  $5,629.00
=========================++============
 Net:                    || $-3,629.00`
```

It can even generate usage for each template based on the frontmatter.

params:
  b:
    required: true
    usage: |
      Required.
      The begin time of report.
      Examples:
        2025-07-01
        Jul
  f:
    usage: The ledger file to parse
    default: ~/.hledger.journal

Run the help command:

$ mdsh hledger_monthly.md -h
Usage of params:
  -b string
    	Required.
    	The begin time of report.
    	Examples:
    	  2025
    	  Jul
    	 (default "2011-01")
  -e string
    	Required.
    	The end time of report.
    	Same format as -b
    	 (default "2011-02")
  -f string
    	The ledger file to parse (default "examples/ledger.j")

Output Filename Template

The default setting is writing the output to stdout. If you want to save it in a file. You can do so by specifying output: in frontmatter.

output: monthly_report_{{.b}}.md

When running mdsh hledger_monthly.md -b 2025-07 -e 2025-08, it saves the output to monthly_report_2025-07.md. It helps you remain the naming consistency with ease.

Not only parameters, you can also put shell script into it. For example:

output: sys-report-{{ raw "date --iso-8601" }}.md

Then it will write the result to sys-report-2025-07-25.md.

Use Case Ideas

mdsh has great potential in areas that require lots of shell scripting and documentation, like sysadmin, devops, and security. It’s also good for creating documentation and tutorials, reducing the hassle of pasting command outputs over and over.

You can make it fit into your workflow by defining your own templates, with usage notes inside. Thanks to the rich features of Go’s template engine, it allows huge extensibility. You can apply condition checks ({{ if }}, {{ with }}) or even loops.

Some potential usages are:

1. Sysadmin/DevOps: system snapshots, cluster health
2. Documentation: release notes, test results
3. Education: lab reports, tutorials
4. Security/Compliance: audits, vulnerability scans
5. Personal Finance: hledger, budget reports (what I’m using it for)

And many more waiting for you to discover!

If you found this project useful, please give me a star on GitHub 🌟

Side note: I developed the first version of mdsh within 2 hours at midnight while trying out Zed, and was impressed by its performance. I didn’t use much AI for this project—sometimes you just need time and space to enjoy programming.

Currently Reading

• Yuval Noah Harari: Nexus
• Ryder Carroll: The Bullet Journal Method
• Dung Kai-cheung: The Learning Age

2025

• Shauna Shapiro: Good Morning, I Love You
• Richard V. Reeves: Of Boys and Men
• Dung Kai-cheung: The Annals of Time: The Light of Mute Porcelain
• Pan Bo-cheng: Becoming a Boxer

2024

• Erich Fromm: The Art of Loving
• James Clear: Atomic Habits
• Tsai Yu-che: Good Rest
• Chu Chia-an: Video Game Philosophy
• R.F. Kuang: Yellowface
• Dale Carnegie: How to Win Friends and Influence People
• Seth Godin: Linchpin

Want to Read

• Mihaly Csikszentmihalyi: Flow: The Psychology of Optimal Experience
• R.F. Kuang: Babel
• Yeh Hao: Political Jet Lag
• Xu Chenggang: Institutional Genes
• Ekkehard Martens: Good Philosophy Bites

Hardware

• Laptop: Framework 13
• Gaming laptop: Razer Blade 15, battery swelled up, now using as desktop gaming rig
• Mouse: Elecom EX-G XL extra large, super comfy grip
• Running watch: Garmin Forerunner 165
• Ebook Reader: BOOX Tab Ultra C

Software

• OS: Fedora 42 / Linux Mint 22
• IDE: Cursor
• Editor: VIM
• Browser: Brave
• Knowledge base: Heptabase, the best note-taking app. My referral code
• Epub reader: Foliate
• Chinese input: Array input method

Self-host

• Router: MikroTik hEX. Super solid, can customize all port connections
• Cloud storage: Nextcloud
• Search aggregator: SearXNG, combines Google, DuckDuckGo, Bing results and protects your privacy
• Bookmark: Linkwarden. Collect links, archive, backup web content
• Matrix Server: Synapse
• Email Server: Postfix+Dovecot using emailwiz

Services

• Email: ProtonMail Essential Plan
• Communication
  • Signal
  • Matrix
  • Telegram
  • Plus whatever everyone else uses
• Password Manager: Bitwarden

Mobile Apps

• F-Droid: Free software app store for Android
• Feeder: Best RSS reader, no contest

2025

Stock traffic light analysis tool. Supports dividend yield calculations, import/export of watchlists, and stock filtering by yield.

Stack: TypeScript, React, Redux, Cheerio, Cloudflare Worker

user: guess
bot: From what number?
user:: 25
bot: To what number?
user: 100
bot: Guess a number between 25 to 100
user: 64
bot: too small
user: 91
bot: too large
……
user: 83
bot: Correct! You spent 6 times to guess this number.

However, the common way we dealing with requests in the backend is one-request-one-response. That would be a disaster to separate a lot of handlers from the conversation. Why? Think about how to store the states? In global variables? Or database? Or Redis? Once you ask users one more question, you need to change the schema of your state, and the code becomes more complex.

In the following, I will show you how to deal with conversations and write the handler in a simple and straightforward way like this:

    def guess(self):
        '''Game function'''
        min_value = self.ask_number('From what number?')
        max_value = self.ask_number('To what number?')
        secret = randint(min_value, max_value)
        msg = f'Guess a number between {min_value} to {max_value}'
        counter = 0
        while True:
            counter += 1
            answer = self.ask_number(msg)
            if answer > secret:
                msg = 'Too large'
            elif answer < secret:
                msg = 'Too small'
            else:
                break
        self.reply(f'You spent {counter} times to guess the secret number.')

I will write a LINE bot for example, but it doesn’t matter what platform you develop to. I will use Django and it’s okay if you use other frameworks.

Setup Environment

It’s for setting up the bot, you can skip this if you know it.

Clone my repo:

git clone https://github.com/lancatlin/python-chatbot-context.git
cd python-chatbot-context
pipenv install
pipenv shell

Go to LINE Developers to create a bot. Issue the token and your secret, put them in a .env file.

LINE_TOKEN=YOUR_TOKEN
LINE_SECRET=YOUR_SECRET

Then start Django.

python manage.py migrate 	# for first execution
python manage.py runserver

Use Ngrok or something similar to tunnel the localhost:8000 to a public endpoint, and register the URL to LINE Messaging API.

Idea Describe

The main idea is to block the command thread until another message is received. When the program receives the ‘guess’ command, it will be executed in the command thread. Once the program needs input from the user, it put a message in the room’s “requests queue”. Then when the message comes in at another thread, it checks the room’s requests queue and puts the message in the responses queue if not empty.

Implement

We implement it as MessageQueue class:

# guess/message_queue.py
import queue
from threading import RLock
from .line import get_room


class RequestTimout(Exception):
    pass


class MessageQueue:
    __lock = RLock()
    __requests = {}
    __responses = {}

    @classmethod
    def create_if_not_exists(cls, room):
        '''Create the requests and responses queues for the room if not exists'''
        with cls.__lock:
            if room not in cls.__requests:
                cls.__requests[room] = queue.Queue(maxsize=1)

            if room not in cls.__responses:
                cls.__responses[room] = queue.Queue(maxsize=1)

    @classmethod
    def handle(cls, event):
        '''Handle the message, check whether there is room request for'''
        room = get_room(event)
        cls.create_if_not_exists(room)

        try:
            if not cls.__requests[room].empty():
                cls.__responses[room].put(event, timeout=1)
                cls.__requests[room].get()
                return True
            return False
        except queue.Empty:
            '''No request, ignore the message'''
            return False

    @classmethod
    def request(cls, room, timeout=30):
        '''Request a message, block until message comes in or timeout'''
        try:
            cls.create_if_not_exists(room)

            cls.__requests[room].put_nowait(True)
            return cls.__responses[room].get(timeout=timeout)

        except queue.Empty:
            MessageQueue.clear(room)
            raise RequestTimout

    @classmethod
    def clear(cls, room):
        '''Clear the requests'''
        cls.create_if_not_exists(room)
        try:
            cls.__requests[room].get_nowait()
        except queue.Empty:
            pass

With this, we can implement our guess app very easily.

# guess/guess.py
from .message_queue import MessageQueue, RequestTimout
from .line import reply_text, get_room, get_msg
from random import randint


class Guess:
    '''Guess handle a guess number game'''

    def __init__(self, event):
        self.event = event
        try:
            self.guess()
        except RequestTimout:
            self.reply('Timeout')

    def guess(self):
        '''Game function'''
        min_value = self.ask_number('From what number?')
        max_value = self.ask_number('To what number?')
        secret = randint(min_value, max_value)
        msg = f'Guess a number between {min_value} to {max_value}'
        counter = 0
        while True:
            counter += 1
            answer = self.ask_number(msg)
            if answer > secret:
                msg = 'Too large'
            elif answer < secret:
                msg = 'Too small'
            else:
                break
        self.reply(f'You spent {counter} times to guess the secret number.')

    def ask(self, *msg):
        '''Ask a question to current user'''
        self.reply(*msg)
        self.event = MessageQueue.request(get_room(self.event))
        return get_msg(self.event)

    def ask_number(self, *msg):
        '''Ask a number, if not number, ask again'''
        try:
            content = self.ask(*msg)
            return int(content)
        except ValueError:
            return self.ask_number('Please input an integer.', *msg)

    def reply(self, *msg):
        '''Reply words to user'''
        reply_text(self.event, *msg)

You can see the main function is straightforward, with only 17 lines of code. What’s more, it can handle multiple user inputs at the same time.

Get full code on GitHub.

Special thanks to YukinaMochizuki for giving me the initial idea from his Notion bot project.

Given a function like the following. How to see the stdout in real-time in the browser?

import time


def job(times):
    for i in range(times):
        print(f'Task #{i}')
        time.sleep(1)
    print('Done')
    time.sleep(0.5)

Streaming Response

Normally, responses are sent after all the data has been collected. However, sometimes we can’t wait until the data is prepared. In this case, we’ll use streaming response. In Django, it’s StreamingHttpResponse. I’ll call it SHR in the following article. StreamingHttpResponse accepts an iterator for input. It sends the value each time getting a new value from the iterator. To use it, we only need to implement an iterator function. It will send the value from yield to the user’s browser in real-time.

# Example of StreamingHttpResponse

from django.http.response import StreamingHttpResponse
def example():
	for i in range(5):
        # Add <br> to break line in browser
		yield f'{i}<br>'

def stream(request):
    return StreamingHttpResponse(example())

Output (in browser):

0
1
2
3
4

Threading

As we execute the task and stream output at the same time, we need concurrence. In Python, there are multiple choices, like threading, multiprocessing, etc. I’ll use threading in this article because it is easier for me.

# Example of threading

from threading import Thread
import time

def example(times):
	for i in range(times):
		print(i)
		time.sleep(1)

# Create Thread
thread = Thread(target=example, args=(5,))

# Start Thread
thread.start()

time.sleep(2)
print("This is printed in the main thread")

# Waiting thread to be done
thread.join()

Output:

0
1
This is printed in the main thread
2
3
4

Redirect Stdout

To change the location where Python print, we need to change sys. stdout. It accepts any File-like object. Specifically, we need to define an object with the write method.

# Example of redirect stdout
import sys

class Printer:
    def __init__(self):
        self.contents = []

    def write(self, value):
        self.contents.append(value)

printer = Printer()
sys.stdout = printer

print('This should be saved in printer')

sys.stdout = sys.__stdout__

print('This should be printed to stdout')

print(printer.contents)

Output:

This should be printed to stdout
['This should be saved in printer', '\n']

Implement Redirecting Stdout to Streaming Response

Environment

Python 3.8.5

Django 3.2

First, create Django Project

pip install django
django-admin startproject console_streaming
cd console_streaming
python manage.py startapp web

Install web

# console_streaming/settings.py

INSTALLED_APPS = [
	...
    # Add web
    'web',
]

Create a view

# web/views.py

def stream(request):
    # implement later
    pass

Bind to URL

# console_streaming/urls.py

from django.urls import path
from web import views

urlpatterns = [
    path('stream/', views.stream),
]

Testing Task

This is the testing function we’re going to use. It will repeat printing a line and waiting a second for n times, and then print “Done”.

# web/views.py
import time


def job(times):
    for i in range(times):
        print(f'Task #{i}')
        time.sleep(1)
    print('Done')
    time.sleep(0.5)

Printer class

We implement a Printer class to handle stdout, and we’ll only use one instance in the whale program life cycle. Because sys.stdout does not thread-specific, if we use different stdout in different requests, one would grab stdout from another. So I use a dictionary to store the queue for different threads, and use current_thread() to identify and pick the right queue. If the current thread hasn’t registered to Printer, use the default stdout.

# web/views.py
from queue import Queue
from threading import current_thread
import sys


class Printer:
    def __init__(self):
        self.queues = {}

    def write(self, value):
        '''handle stdout'''
        queue = self.queues.get(current_thread().name)
        if queue:
            queue.put(value)
        else:
            sys.__stdout__.write(value)

    def flush(self):
        '''Django would crash without this'''
        pass

    def register(self, thread):
        '''register a Thread'''
        queue = Queue()
        self.queues[thread.name] = queue
        return queue

    def clean(self, thread):
        '''delete a Thread'''
        del self.queues[thread.name]
        
# Initialize a Printer instance
printer = Printer()
sys.stdout = printer

Streamer class

Next, we’re going to implement concurrent execution and streaming response by a Streamer class. It will initialize a thread, and register it to the printer to get a queue. Then it repeats to read the value from queue and yield to response until the thread ends.

from threading import Thread


class Steamer:
    def __init__(self, target, args):
        self.thread = Thread(target=target, args=args)
        self.queue = printer.register(self.thread)

    def start(self):
        self.thread.start()
        print('This should be stdout')
        while self.thread.is_alive():
            try:
                item = self.queue.get_nowait()
                yield f'{item}<br>'
            except Empty:
                pass
        yield 'End'
        printer.clean(self.thread)

def stream(request):
    streamer = Steamer(job, (10,))
    return StreamingHttpResponse(streamer.start())

Run Django server

$ python manage.py runserver

Open http://localhost:8000/stream/

Then you can see

Each time you make a request, you can see one output in the terminal.

This should be stdout

Full views.py

from django.http.response import StreamingHttpResponse
from queue import Queue, Empty
from threading import Thread, current_thread
import time
import sys


class Printer:
    def __init__(self):
        self.queues = {}

    def write(self, value):
        '''handle stdout'''
        queue = self.queues.get(current_thread().name)
        if queue:
            queue.put(value)
        else:
            sys.__stdout__.write(value)

    def flush(self):
        '''Django would crash without this'''
        pass

    def register(self, thread):
        '''register a Thread'''
        queue = Queue()
        self.queues[thread.name] = queue
        return queue

    def clean(self, thread):
        '''delete a Thread'''
        del self.queues[thread.name]


printer = Printer()
sys.stdout = printer


class Steamer:
    def __init__(self, target, args):
        self.thread = Thread(target=target, args=args)
        self.queue = printer.register(self.thread)

    def start(self):
        self.thread.start()
        print('This should be stdout')
        while self.thread.is_alive():
            try:
                item = self.queue.get_nowait()
                yield f'{item}<br>'
            except Empty:
                pass
        yield 'End'
        printer.clean(self.thread)


def job(times):
    for i in range(times):
        print(f'Task #{i}')
        time.sleep(1)
    print('Done')
    time.sleep(0.5)


def stream(request):
    streamer = Steamer(job, (10,))
    return StreamingHttpResponse(streamer.start())

Complete code on GitHub

References

• Python Docs: threading
• Python Docs: queue
• Chase Seibert: Redirect console output to a Django HttpResponse
• thread specific sys.stdout?
• G. T. Wang: Python 多執行緒 threading 模組平行化程式設計教學

About this site

My personal blog featuring technical insights, book notes, and personal thoughts.

You may want to know:

• /projects My projects
• /now What I’m up to these days
• /use What I use
• /books What I read

Contact me

• Email: wancat@wancat.cc
• Matrix: @wancat:linchpins.cloud
• GitHub
• Matters