Pixel Li

Tech notes: making a ten-year-old Flask site static and moving it to free Cloudflare hosting

Thu, 05 Nov 2026 00:00:00 +0000

This is a complete record for myself: the next time I change this site, or move another old site the same way, read this first. The site was built for a lab many years ago; below I just call it “this site” and leave out its name and domain. The one doing the work was Claude Code on a Mac mini; I made the decisions and clicked confirm.

Summary at a glance

Item	Before	After
Hosting	One AWS Lightsail server, running only this site	Cloudflare Workers static assets, free
Cost	$35.65 for six months, averaging $5.94 a month, about $71 a year	Server cost 0; only the domain registration fee is left
Stack	Python 2.7 + Flask 0.12 + Apache, Ubuntu 16.04 (unsupported since 2021)	Python 3.12 + Flask 3 exporting static files; the admin runs only locally
Update frequency	Changed about twice a year	Unchanged; after editing, `make publish` goes live in half a minute
Large files	S3: research page videos + PyMOL downloads, 26 files, 362MB	Videos go into the site; 17 download files go on R2 (free tier 10GB)
Time	2 months of development back then; then deployment, data updates, and for 2.0 adding the admin and writing tutorials, so there was always maintenance work	Static conversion done in one day
Trade-off	—	Direct connections from mainland China got slower (see the measurements below); I accepted it

To keep it stable, I never ran any other service on this server. I changed the content twice a year and still paid $6 every month. That’s money I should have saved long ago.

Why it can be made static

First I listed the “dynamic” parts clearly, so I could tell whether they could be moved:

Part	How it used to work	After static conversion
6 pages	Jinja templates + SQLite queries	Exported as HTML
10 research subpages	`/research/<name>` renders the matching template	Exported one by one
3 JSON endpoints	`?selectedItem=…`, `?selectedTag=…`, `?tag=…` query strings	Changed to path parameters, each address exported as a `.json` file
Admin	Flask-Admin, Basic Auth, edited directly on the live site	Kept as is, runs only locally
Page cache	Flask-Cache, cleared after admin submissions	Removed

On the visitor side there are no forms, logins or search — it’s all read-only. That’s enough. The data is small too: 221 papers, 105 structures, 55 members, a 164KB database, 39MB of images.

Export

I didn’t use Frozen-Flask; I wrote an 88-line freeze.py that requests each URL through Flask’s test_client and writes the file. Reasons:

I wanted /people written as people.html, so the hosting platform maps /people to it automatically; Frozen-Flask by default writes extensionless files.
Endpoints with query strings can’t be exported, so the routes had to change first.

How I changed the endpoints:

/current_structure?selectedItem=5GMK  →  /data/structure/5GMK.json
/orientation_tag?selectedTag=…        →  /data/orientation/0.json   (numbered in page order)
/current_event?tag=Fun Time           →  /data/event/fun-time.json

Orientation names contain spaces and β, which don’t work well as filenames, so I used numbers. I changed one or two request URLs in each of the two front-end JS files.

While I was at it, I also wrote two files the hosting platform understands:

_redirects   /index → /, and one old section address redirecting to the new section
_headers     /static/* cached 1 day; /data/* cached 10 minutes

_headers was added after going live: Workers static assets default to max-age=0, must-revalidate, so the browser has to check back with the server for every image; a structure page with dozens of thumbnails means dozens of round trips. The old server cached for 12 hours.

Python 2 → 3

The code base isn’t big (about 700 lines excluding data), but a few places fail silently:

Problem	Symptom	Fix
`zip()` returns an iterator in Python 3	The template loop is drained after one pass; `json.dumps` serialization fails	Wrap in `list()`
`r.encode('utf-8')`	Orientation names become `b'…'` written into the page	Removed
`flask.json.dumps(…, cls=…)`	Since Flask 2.3 `cls` is ignored, the custom encoder doesn’t take effect, raising `Category is not JSON serializable`	Switched to the standard library `json`
SQLAlchemy 2 single-column queries return `Row`	Not a tuple, so the encoder doesn’t accept it	`[list(r) for r in rows]`
Custom encoder scans fields with `dir(obj)`	SQLAlchemy 2 adds attributes like `registry`	Changed to take only `mapper.column_attrs`
`__unicode__` references `self.name`, but the model has no `name`	Never called under Python 2; Flask-Admin calls `__str__` under Python 3	Changed to the real field
Flask-Admin 2 only ships Bootstrap 4	`label label-info` and `well` in 24 custom admin templates stopped working	Replaced with `badge` and `card`
One global session, the local dev server is multi-threaded	Occasional mix-ups	`scoped_session` + `remove()` in `teardown_appcontext`
Database path hardcoded to `/home/<user>/…`	Not found on another machine	Changed to a path relative to the project directory

I also turned up an old bug that I planted myself back then. The 4th tab name on the structure page contains a Greek letter; the tab text goes through HTML decoding (β → β), but the name list passed to the endpoint wasn’t decoded, so the two sides didn’t match. It used to show up only because the server had a hardcoded fallback. After static conversion the fallback was gone, and the problem surfaced. Fixed by decoding before comparing.

Verification: line-by-line comparison with the live site

Before changing anything, I saved a snapshot of the live site: 7 pages, 12 research subpages, 112 JSON endpoints (one per structure). After export I compared them one by one:

The 19 pages are line-by-line identical after stripping whitespace;
The 112 JSON files match (ignoring the related fields with null values that the old encoder emitted extra);
I clicked through it in a headless browser: the 4 tabs on the structure page add up to 23+36+18+28=105 structures, matching the database count; detail pages have images and text; the 3 lab activity tabs work;
Screenshots at 375 (phone), 768 (tablet) and 1400 (desktop) widths: list pages are pixel-identical to the live site.

I tested the admin on a temporary copy, without touching the real data: create, edit and delete in 15 sections; after uploading a structure image, the main image gets cropped to 500×500 and a 100×100 thumbnail is generated automatically; deleting a record deletes the file along with the thumbnail; uploading and deleting media files; then clicked through the new-paper form in a real browser (the year is a select2 dropdown), saved it, and it showed up on the paper page.

Deployment: Workers static assets

I originally planned to use Cloudflare Pages. The new wrangler (4.157) runs pages project create by redirecting to creating a Worker, and fails if no static directory is given. Pages has been merged into Workers; what’s recommended now is Workers static assets, with the same free tier, and it supports _redirects, _headers and 404 pages.

{
  "name": "<worker name>",
  "compatibility_date": "2026-11-01",
  "routes": [{ "pattern": "<domain>", "custom_domain": true }],
  "workers_dev": false,
  "preview_urls": false,
  "assets": {
    "directory": "./build",
    "html_handling": "auto-trailing-slash",
    "not_found_handling": "404-page"
  }
}

The permissions the API token needs (the first dropdown is Zone or Account; pick the wrong one and the later items won’t show up):

Scope	Permission	Purpose
Account	Workers Scripts · Edit	Deploy
Account	Workers R2 Storage · Edit	Create buckets, upload files, bind the domain
Zone (only these domains selected)	DNS · Edit	Change records (note: not DNS Settings)
Zone	Workers Routes · Edit	Bind custom domain
Zone	Dynamic URL Redirects · Edit	Redirect rules

If the Token only has Pages permissions, wrangler can’t read the account ID, and CLOUDFLARE_ACCOUNT_ID has to be set manually.

For day-to-day use I wrapped it in a Makefile:

make admin     # open the admin locally to edit content
make publish   # export → deploy → commit and push the database and images to GitHub

The auto-commit in publish is there because the content (database, images) is also in the repo. It used to be a manual step, and if I forgot, the “backup” on GitHub was actually stale. I will definitely forget.

Moving S3 to R2

The videos and download files on S3 have hotlink protection: only requests whose Referer is the https version of this site get through. So a plain curl gets a 403, but with the Referer it downloads fine, no AWS keys needed:

curl -H "Referer: https://<domain>/" -o file "https://s3.<region>.amazonaws.com/<bucket>/<path>"

9 videos (1.5–4.7MB) went straight into the site. The + in filenames was changed to _ to avoid ambiguity in URLs.
17 PyMOL files (largest 47MB, over the 25MB per-file limit for Workers static assets) went on R2, bound to the subdomain files.<domain>. Uploaded with wrangler r2 object put --remote; after uploading, each was downloaded and its SHA-256 compared, matching the S3 originals.

After binding the custom domain, a few files returned 403 for the first minute; once the edge nodes synced, they were fine.

Domain

Changing nameservers

In Cloudflare, go to Add a site → Connect a domain, and the DNS records are imported automatically. After importing, first change the records pointing at the old server to a grey cloud (DNS only): the old server does its own http→https redirect, and some Cloudflare SSL modes send requests to the origin over HTTP, so the two together can cause an infinite redirect loop. Once they’re grey, the site is still served by the old server until the switch.

Gotcha: different domains aren’t necessarily assigned the same pair of nameservers. I filled in the same pair for two domains in bulk at GoDaddy, and one of them stayed pending; I checked the API and found it had been assigned a different pair.

Switching

Delete the A record for the main domain, then immediately bind the Worker custom domain via the API (the certificate is issued automatically). Visitors who still have the old record cached keep going to the old server, which is still running, so there was no downtime.

For the domain used only for redirects: point the root record at the placeholder address 192.0.2.1 with the proxy on, then add a 301 rule so requests are redirected at the Cloudflare edge without hitting the origin. The target address in the rule:

Keep the path: target_url.expression = concat("https://<main domain>", http.request.uri.path)
Fixed address: target_url.value = "https://…"     ← writing this as an expression gives a Filter parsing error

Registrar

For the same .com, GoDaddy renews at $22.99/year, Cloudflare at cost, $11.17/year (it just went up from $10.46 on November 1), a difference of $11.82 a year, roughly half the price. To transfer, first make the domain active on Cloudflare, then unlock it at GoDaddy and get the authorization code; you pay for 1 year at transfer time, and it’s added after the existing expiry date, so nothing is wasted. Don’t change the registrant info before the transfer completes, or the domain gets locked for 60 days.

Access from mainland China

This is the only thing that got worse. On the afternoon of 2026-11-05, over the same home broadband connection, I connected directly and requested one 2KB logo each time:

	Success	Average time
Cloudflare free plan	17/20, 3 timeouts	4–8 seconds
Old server (AWS Ohio, US)	10/10	0.9 seconds

Breaking it down, establishing the TCP connection takes 0.27 seconds, about the same as with AWS; the slowness comes from the occasional 3–5 second stall afterwards, as if from packet loss and retransmission. Access from overseas is faster, by contrast. After looking at the data, I decided to accept it. No rollback. To get fast access in mainland China, the only option is ICP filing and a domestic CDN.

Also, *.workers.dev is blocked entirely in mainland China: DNS resolves to the wrong address, and even a connection to the real IP gets reset during the TLS handshake. The test address could only be viewed through a proxy; once I bind my own domain, it isn’t affected. I later shut down that test address too (workers_dev: false).

While I was at it: moving the blog’s image host back into the repo

In 2020 I wrote a post about setting up an image host with Amazon S3 + uPic. That bucket had 44 images, 39 of which were referenced by the blog, 3.3MB in total. I’d long forgotten the key and secret from back then. Fortunately the images were public anyway, so I could just download them, no key needed. They went into the repo under img/markdown-img/, and the links in 10 posts and the about page were changed to paths within the site. Later posts already put images straight into /img/.

To see all the files in a bucket when you don’t have a key, use CloudShell in the top-right corner of the AWS console, which uses your current logged-in identity:

aws s3 ls s3://<bucket> --recursive --summarize | tail -3

How much to let the AI do

Claude Code’s safety checks stopped me twice: once when deleting the DNS records for the production domain, and once when making an R2 bucket public on a subdomain. It was right to stop me, both steps affect the outside world and are hard to undo. After I’d read the list of changes and the rollback plan it laid out, I replied “confirm”, and only then did it go ahead. Another time it wanted to borrow another Token to look up the account ID, and that was blocked too: that Token is for renewing certificates for another service and shouldn’t be repurposed.

Pitfalls

In zsh, a URL containing ? without quotes is treated as a glob, and the command fails with no matches found.
zsh doesn’t split variables on spaces, so set -- $r doesn’t give you multiple arguments, and my validation script flagged everything as “abnormal” because of it.
Going through a proxy from my machine, each request to Cloudflare takes 1–2 seconds; after a headless browser views a few pages with video, the next page hangs and times out. Interactive tests need a separate page.
Workers static assets have a per-file limit of 25MB.
The Google Analytics the pages referenced was the old UA code that had stopped collecting data back in 2023, and it was also slowing down page loads, so I removed it.

Not done yet

After monitoring it for a week or two, delete the S3 bucket and shut down the old server; then remove the test subdomain record pointing at the old server and the deploy/ directory in the repo.
I haven’t tested the speed in mainland China during peak hours; I assume it’s only worse.
The other 10 defensively registered .com domains are still at GoDaddy; I’ll decide before they expire whether to transfer them.

Mac mini Home Server: Set Up a Workbench in One Sentence, Open Source

Sat, 31 Oct 2026 00:00:00 +0000

A home server sounds very geeky, like a toy that only programmers have. But in the era of large models, it’s actually something for every household. Because the code work of deployment, management and maintenance is exactly one of the things today’s large models are best at. I turned the pitfalls I ran into into an open-source project, so that AI can set up a workbench in one sentence.

The one at my home is a Mac mini. I actually thought about it for a long time before buying the Mac mini — I already had an mbp — with one more computer, would I even use it enough? But after buying it, I found that the more I use it, the more I like it. The core of a home server is running 24/7 without interruption. That means whatever service you want to use, whenever you want it, it’s there to respond. And over time, the automated services naturally get richer — this is a device that keeps growing along with you, it’s an asset. This is what it looks like right now:

There are 10 services in total. 7 on the Mac mini: movie library, local video generation, voiceover, local large model, the workbench I use to write this WeChat account, investment bookkeeping, and subtitles. The other 3 are on the NAS and Raspberry Pi next to it: Synology admin, n8n and Home Assistant.

What a home server is

Put simply, it’s a computer at home that’s on 24 hours a day, running your own always-on services.

Things a home server can do include but are not limited to:

Purpose	Common services	What it does for you
Media	Jellyfin	Downloaded movies automatically get posters, and you can watch them on your TV, projector or phone
Photos	Immich	Phone photos are backed up automatically and searchable by face, location, or similar image
Passwords	Vaultwarden	The family password vault; any Bitwarden client can connect
Ad blocking	AdGuard Home	Ad blocking across all home devices
Automation	n8n, Home Assistant	Scrape news on a schedule and send it to your phone; the desk rises by itself after you sit too long
AI	Ollama etc.	Run large models locally; chat and generation never leave this machine

There are also some services that don’t need a backend but are actually very well suited to running on one. For example, what I use most right now is Paseo. It’s a console for coding Agents like Claude Code and Codex: the Agent runs permanently on the Mac mini, and I can connect from anywhere to check progress and give the next instruction. A session started on the computer can be continued on the phone, and vice versa — the multi-device session sync problem is gone entirely. That’s what lets AI now work steadily across multiple devices over the long term. I’ll go into its benefits in detail next time.

What machine is good for a home server? My take:

Mac mini is the best fit. Low power, quiet, fine to leave on long-term, and Apple chips can run local AI.
NAS is good for storing data. Install too many services and it struggles.
Raspberry Pi is good for running one or two lightweight ones, like Home Assistant.
An idle Linux computer also works, but it’s a second choice.

Once you have a lot of services, trouble starts

The 4 troubles I ran into:

Can’t remember the addresses. Each service has a port, 8096 is movies, 8190 is video generation, 8123 is smart home… 10 of them, impossible to remember, I have to dig through notes every time.
The browser says “not secure”. Home services default to http, and some features (like recording, copying) don’t work on insecure pages.
Want to use it from outside, but afraid of exposure. Opening a port on the router is the simplest, but it’s like leaving your front door open on the public internet, and port-scanning bots are looking for doors like that all day long.
Don’t know when something is down. You usually only find out a service stopped when you need to use it.

The workbench: one entry point to manage all services

My solution is to build a workbench for these always-on services. It does just 4 things:

A name for each service: jellyfin.yourdomain.com, ha.yourdomain.com, no more remembering ports.
Proper certificates: the browser shows a padlock, auto-renewed.
Only you can open it: even if others know the address, they can’t connect.
One dashboard: whether each service is online, and the machine’s CPU, memory, disk and temperature, all at a glance; plus an automatic checkup once a day.

Maintenance is simple too. All services are written in one list, adding a service is adding a line, and the domain, certificate, card and checkup all update automatically.

Several ways to access from outside

“Only you can open it” is a given on the LAN; the key is how to connect back home from outside. The common ones:

Method	How it connects	Who can access	Things to note
Public IP + port forwarding	Open a port on the router; DDNS follows IP changes	The whole world	Many home broadband connections have no public IP; exposed to the public internet, security rests entirely on the service itself
Tunneling (frp, Oray etc.)	Borrow a relay server	The whole world by default	Speed depends on the relay; mostly paid
Cloudflare Tunnel	Your home connects out to Cloudflare	The whole world, login can be added	Unstable access from within China; not suitable for streaming video
Tailscale / ZeroTier	Your devices form a virtual LAN	Only your logged-in devices	An App must be installed on each device

If the services are only for yourself and your family, I recommend the last one. I use Tailscale, and the personal free plan currently allows 6 users, with unlimited devices. At home it automatically connects directly over the LAN, and when you’re out and about you can still connect back. Remote desktop works through it too.

My recommendation: a private URL only you can open

Adding your own domain on top of Tailscale gives you a very comfortable setup:

Step	What to use	Cost
Domain	A domain bought from any registrar, with DNS managed by Cloudflare	Non-`.com` domains are super cheap
Resolution	One wildcard record pointing to the server’s Tailscale address	Free
Certificate	Let’s Encrypt, DNS validation	Free
Entry	Caddy, routes requests to each service by domain	Free
Connection	Tailscale	Free for personal use

The result: I open mini.uulili.com and it’s the workbench, and clicking into each service gives it its own address and SSL padlock. This domain resolves publicly, but it resolves to an address inside Tailscale, so devices not on my Tailscale network can’t connect even if they try.

homelab-desk: let AI set it up in one sentence

The workbench project is called homelab-desk, and it’s already open source on GitHub under the MIT license:

GitHub project address

https://github.com/shisaq/homelab-desk

It does these things:

Deployment overview: reads your service list, generates the Caddy config, requests certificates, allows only Tailscale, and installs itself as a background service that starts on boot. It can be run repeatedly — just run it again after changing the list.
Real-time dashboard: whether each service is online, how fast it responds, and the last 1 hour of records; the machine’s CPU (every core), memory composition and pressure, disk and network, and with plugins also temperature, GPU and UPS.
Pick a style: 4 themes, each with light and dark versions; see the next section for how they look.
Recommended services: a built-in catalog covering media, photos, passwords, ad blocking, automation, AI, downloads, reading and more, 30 items in total. Each item says who it’s for, how to install it, and what to watch out for behind a reverse proxy.
Daily checkup: checks each service and how many days the certificate has left, and can be hooked up to your own notification channel.

The pitfalls I ran into above, the project handles them all. For example, for the restriction on listening on 443, it switches to allowing only Tailscale by source; the online check is done on the server, avoiding the browser’s cross-origin false positives; services like Home Assistant that need extra configuration are spelled out directly in the catalog.

I also made a few different styles along the way

The workbench has 4 themes in total: Glass, Apple’s Liquid Glass, Minimal and Terminal, each with light and dark versions, switchable from the top right corner of the page.

How to use it

Clone the project, link the skill inside it to Claude Code or Codex, then say one sentence to it:

Say to Claude Code or Codex

Help me set up a home server workbench with homelab-desk

It will check the prerequisites, walk you through creating a Token and DNS records in Cloudflare, deploy everything, and finally verify it. Adding a service later is also one sentence:

Adding a service later

Add Immich

If you don’t want to use AI, you can also manually run the 4 commands init, doctor, dns, deploy.

Why not make it Docker? Docker on Mac runs in a virtual machine, so it can’t get the Tailscale address, and it can’t read the host’s temperature or GPU. The project itself is just Caddy, a small Python service and a static page, so running it natively is simpler. Your services can run anywhere, including in Docker; the project only cares about “address:port”.

Homepage, Homarr and Dashy handle navigation pages, and Uptime Kuma handles monitoring. homelab-desk manages the whole chain from zero to usable. If you’re already using them, you can add them as services too.

Who it’s for

You already have an always-on Mac running a few services: use it directly.
You’re on Linux: the adaptation code is already written, but hasn’t been verified on real hardware yet, so testing and feedback are welcome.
You don’t have a server yet: pick one or two services you want from the table above, and a single Mac mini can run them.
You want to expose services to friends and have them open in a browser directly, without Tailscale: this project doesn’t handle that. That needs a public server and user management, and the security issues alone are enough to give you a headache.

The prerequisites are 3 things: a domain hosted on Cloudflare, Tailscale installed and logged in, and Claude Code or Codex (not needed for manual deployment).

To sum up: the value of a home server is in those services, and the workbench lets you keep them manageable. Project address once more, and I’d love a star:

GitHub project address

https://github.com/shisaq/homelab-desk

If you run into problems while using it, feel free to leave a comment or open an issue on GitHub. I sincerely hope you have few liabilities and many assets.

Blog edition extras

For a few of the services on the workbench, the blog has separate hands-on posts:

Local large model: Mac mini running 27B, up to 35 token/s
Local video generation (H3 Studio): Running AI video on a Mac mini: how much memory, how long to generate?
Voiceover (TTS mixing desk): Tech notes: locally fine-tuning Qwen3-TTS voices on a Mac mini

Technical notes: Local fine-tuning of Qwen3-TTS voices on a Mac mini

Thu, 29 Oct 2026 00:00:00 +0000

This is a complete record for my own reference: next time I train a new voice, or pick this up again in a new conversation, read this first. All the code is in qwen3-tts-console (the web page is in the root directory, the training pipeline is in finetune/). In this post the two people being trained are called speaker A and B.

Summary at a glance

Item	Value
Machine	Mac mini, M5 Pro, 64GB; GPU can use up to 51.8GB (81%)
Reason	Zero-shot cloning from a 10-second reference clip didn’t match the person’s timbre and accent
Source material	A: 6 videos (about 24 minutes) + 1 conversation of 23 minutes; B: 13 videos (about 42 minutes) + the same conversation
Automatic processing	About 90 minutes of material, cut, transcribed and speaker-filtered in a dozen or so minutes
After manual review	A 165 segments / 18.0 minutes; B 361 segments / 38.9 minutes (review took about 1.5 hours)
Training (1.7B, 10 epochs)	A 17 minutes, B 37 minutes, peak memory about 39–41GB
Voiceprint similarity	A: 0.72 → 0.84; B: 0.57 → 0.82 (zero-shot → best epoch)
Character error rate	Below 1% for all versions
Deployment	A uses epoch 8, B uses epoch 10; generating 5 seconds of speech takes about 2 seconds, loading takes 0.5 seconds, and each model is about 3GB
Low memory	0.6B with 20 layers frozen: peak 10.6GB, similarity 0.83, so a 16GB machine should be able to run it

Overall structure

Video ─(extract audio yourself first)─▶ wav
  ─ prep_data.py   FunASR transcription + cut into 2–10 seconds + CAM++ speaker filtering      (.venv: torch + funasr)
  ─ review.py      web review: listen, fix text, keep/discard              (same as above)
  ─ build_train.py Qwen3-TTS-Tokenizer-12Hz encodes into speech tokens  (.venv-train: qwen-tts + torch)
  ─ sft.py         fine-tune on the Base model, save as custom_voice checkpoint (same as above, MPS)
  ─ gen_samples.py convert each epoch to MLX 8bit, generate sample audio together with zero-shot   (the web page's venv: mlx-audio)
  ─ score_samples.py similarity, character error rate, speaking rate; pick by ear on the comparison page       (.venv)
  ─ ttsd's tuned_voices config ─▶ appears in "My Voices" on the web page

The 3 Python environments are deliberately separated: FunASR, qwen-tts and mlx-audio each pin different dependency versions, and mixing them tends to cause conflicts. Tested versions: funasr 1.4.16, modelscope 1.40.2, qwen-tts 0.1.1, torch 2.14.1; mlx-audio uses the commit pinned in the web page’s requirements.txt.

The web UI itself (ttsd) is a single-file Python service, kept running by launchd and reverse-proxied by Caddy. Models run as 8bit quantized versions through mlx-audio and are unloaded automatically after 10 minutes idle.

Data preparation

Transcription: FunASR, not Whisper

AutoModel(model="paraformer-zh", vad_model="fsmn-vad", punc_model="ct-punc", spk_model="cam++"):

Paraformer-zh: accurate for Chinese, and gives a timestamp for each character. 1.8 minutes of audio transcribes in 12 seconds. English words are often misspelled (Gartner → garten), so segments that are mostly English are discarded outright (more letters than Chinese characters).
fsmn-vad / ct-punc: sentence segmentation and punctuation.
CAM++: voiceprints. Measured: segments from the same person score 0.72–0.75, different people 0.08–0.36, and the two people’s reference recordings score 0.31 against each other. Threshold: ≥ 0.55 keep, 0.45–0.55 tentative, below that discard. The host, interruptions and the other party in the conversation all get filtered out this way.

A FunASR 1.4.16 bug: sentence_info puts each punctuation mark one character late (“开发者。大家好，很高兴” becomes “开发者大。家好很，高兴”), so cutting segments with it breaks words in the middle. The full text text and per-character timestamps timestamp are correct, so I re-cut it myself: tokenize by [A-Za-z']+|punctuation|single Chinese character, the token count and timestamp count match one-to-one (measured to match exactly), break sentences at punctuation, and take the speaker label from the sentence_info segment with the most temporal overlap.

Cutting rules

Sentences from the same speaker with a gap ≤ 0.5 seconds are merged into 2–10-second segments; once a segment reaches 4 seconds and hits a period, cut it off early.
Leave 0.08 / 0.15 seconds at the start and end, but don’t cross the midpoint of the neighbouring sentence.
Normalize the loudness of the voiced parts to -20 dBFS, with peaks no higher than -1 dBFS.
The noise floor is the 10th percentile of 50ms frame energy over the whole audio, with a lower bound of -90 dB (synthesized or denoised audio can contain digital silence; without a lower bound the SNR comes out as 150-something).
Two edited versions of the same event will have duplicate sentences: if text similarity > 0.8 and they come from different files, keep the one with the higher SNR.
Automatic flags: English, filler words (呃嗯额, “uh/um”), repetitions/slips of the tongue, runs of Chinese numerals — look at these first when reviewing.
Normalize the casing of English terms (ai → AI, gpt → GPT); misrecognized product names go into the configured terms.

Manual review

Changes are written to edits.json (by segment id), so re-running data preparation doesn’t lose them. Of A’s 198 segments I changed the text of 55 (29 typos, 19 with English words, 7 punctuation only) and dropped 33. Of B’s 469 segments I changed 109 and dropped 108, which took about 1.5 hours. My impression is that the automatic recognition is already quite accurate, and only a few sentence breaks were wrong.

Training script: 4 problems in the official sft_12hz.py

First, compute the loss on real clips with the untrained Base model: with the right settings, the loss should be very low, since a pretrained model can already predict real speech. The first smoke test gave a loss of 7.5, close to random guessing (vocabulary 3072; a uniform distribution would give about 8.0), so I compared it against the inference code to track it down:

Setting	talker initial loss	sub-model initial loss
Official script	11.9	9.1
Labels shifted only once	7.9	–
Plus `text_projection`	1.2	–
Sub-model uses the previous frame’s hidden state; loss is no longer shifted	–	5.4

Labels shifted twice (QwenLM/Qwen3-TTS#179): the talker’s HF loss shifts internally once, and the script also does [:, 1:] by hand. The model learns to predict the token one frame away, and the symptom is that speech gets faster the longer you train. Fix: don’t slice the input or labels; let the loss function do the shifting itself.
Missing text_projection: at inference, all text vectors (role markers, tts_pad/bos/eos, body text) first go through talker.text_projection, but the training script used the output of text_embedding directly. Both are 2048-dimensional, so no error is raised, and the model kept learning from inputs it never sees at inference.
Sub-model also shifted twice: the logits returned by forward_sub_talker_finetune are already aligned with codec_ids[:, 1:], and the built-in loss shifts them one more position; at inference, the code predictor gets the hidden state of “the position that predicted this frame” (t−1). Fix: hidden[:, :-1][codec_mask[:, 1:]] paired with codec_ids[:, 1:][codec_mask[:, 1:]], computing the cross-entropy myself without the shift.
Weights stored in bf16: at a learning rate of 2e-6, AdamW’s per-step update is smaller than what bf16 can represent, so most of it gets rounded away. Changed to fp32 weight storage with bf16 autocast for compute.

Other settings: learning rate 2e-6, 5% warmup + cosine decay, batch 2 × gradient accumulation 4, gradient clipping 1.0; the speaker vector is the average voiceprint of 64 training clips (more stable than a single reference recording), written into row 3000 of codec_embedding; checkpoints are saved as bf16, tts_model_type changed to custom_voice, spk_id is just this one person.

The training data uses the prefix with no language tag (nothink), so generation must use auto as the language; specifying chinese switches to a prefix the model has never seen. The Base model never learned instructions, so the fine-tuned voice does not support tone descriptions.

Memory: the first run hit swap

Full training of 1.6B parameters (the text embedding layer is trained too) used 44GB. At epoch 2, saving a checkpoint copied the weights once more, so the system started swapping and each step went from 1.2 seconds to 15 seconds. Changed 3 things:

Freeze the text embedding layer: 311 million parameters, 150k tokens, but 18 minutes of audio only uses a few hundred of them. Saves about 4GB, and reduces overfitting a little too (details in the next section).
When saving a checkpoint, move each tensor to the CPU first, then convert to bf16, and call torch.mps.empty_cache() after saving.
Store frozen parameters in bf16 (not updated, so fp32 isn’t needed).

After that, 1.7B full training held steady at 37–41GB and 1.2 seconds per step.

Is freezing the text embedding layer risky?

Freezing doesn’t remove the layer: it still takes part in computation; it just isn’t updated during training and keeps the Base model’s original values.

What it handles. talker.model.text_embedding is a 151936 × 2048 lookup table, one row per token, and it only answers “which character is this”. Everything after it that decides “how this person reads it” is trained:

Part	Shape / size	During training
`text_embedding` (recognizing characters)	151936 × 2048, 311 million parameters	frozen
`text_projection` (translates text vectors for the speech model)	two layers 2048 × 2048	trained
talker 28 layers (how to read, intonation, rhythm)	about 1.4 billion parameters	trained
`codec_embedding` (speech codes, where the speaker vector lives)	3072 × 2048	trained
code predictor (15 layers of speech codes after each frame)	about 170 million parameters	trained
speaker encoder (only used to compute the speaker vector)	–	frozen

Why freezing is actually more stable with little data. Without freezing, at each step only the few hundred rows that appear in the training text get gradients in the embedding layer (AdamW barely moves rows with zero gradient), and after training, “characters it has seen” and “characters it hasn’t” slowly become inconsistent in the model’s eyes: in a new sentence, some characters may sound like him and some may not. With freezing, the 150k tokens stay as they are and remain consistent with each other.

No loss of precision. The Base model’s released weights are already bf16 (text_embedding and text_projection both), so storing the frozen part in bf16 is bit-for-bit identical to the original weights; checkpoints are saved as bf16 anyway.

The real limitation. A frozen embedding layer can’t give a word a “new identity”. If his pronunciation of a word is very particular (a fixed pronunciation for a product name, the reading of a character in a dialect), only the 28 layers behind it can learn that from context; that’s enough most of the time, but if after training a word still comes out wrong every time:

First change how it’s written in the script: a homophone, split it apart, or add a space—that’s the easiest way;
Once you have more data (an hour or two), add --train_text_embedding when training again, it uses about 4GB more. New languages and new dialects fall under this too.

The limits of the evidence. What supports “character recognition isn’t damaged”: after fine-tuning, all versions had a character error rate below 1% on sentences outside the training set, including ones with English words like AI Agent and RPA, and similarity also improved as expected. What I haven’t done: a strict frozen vs. non-frozen comparison. Both voices that went live were trained with freezing, and the non-frozen version only ran for 1 epoch (memory blew up), so there’s no direct data showing that “the two perform the same”. To confirm: same data, batch 1 with text embedding training enabled, train for 6 epochs, compare similarity and character error rate, and listen specifically to a few proper nouns.

How to judge whether it sounds alike

Qwen’s built-in voiceprint encoder can’t be used for evaluation: zero-shot cloning’s similarity to the reference recording was 0.991, but another male voice also scored 0.974. The 8bit and bf16 clones both scored 0.991 (I couldn’t hear a difference either, so 8bit is what I use live).
Use CAM++ and compare against the average voiceprint from 40 real clips of the person, not a single reference recording.
5 sentences outside the training set × 2 random seeds, 10 samples per version; also check the transcription character error rate and speaking rate (a real person is about 5 characters/second; a noticeably faster rate means the label-shift problem).
The score is compared against the training recordings, and the recording environment (microphone, room) can also be learned, so the final pick is by ear. The comparison page puts all versions of the same sentence side by side.

Results

2 epochs of training gave most of the improvement; after that it was basically flat.
Training loss dropped to 0.1–0.2 by epoch 10, and it started memorizing: A’s epoch 10 score fell back, and a few samples had a click. So I save a version every 2 epochs.
For A’s epochs 8 and 10, I also tested 8 more sentences × 3 seeds each: 0.815 vs 0.827, a tie. In the end I picked both by ear from the seed 11 group: A uses epoch 8, B uses epoch 10, and the other epoch is kept as a backup.

Low-memory options

Training for 6 epochs is enough. Using the same 18 minutes of A’s recordings, batch 1 × accumulation 8, measured on a 64GB machine:

Model · setting	Peak	Time	Similarity
1.7B default (batch 2, epoch 6 of a 10-epoch run)	about 39GB	about 10 minutes	0.842
1.7B freeze 20 layers	18.2GB	7 minutes	0.804
1.7B freeze 24 layers	15.6GB	6 minutes	0.785
1.7B freeze 26 layers	13.6GB	5.5 minutes	0.789
0.6B no freezing	16.1GB	7 minutes	0.808
0.6B freeze 14 layers	11.9GB	5 minutes	0.827
0.6B freeze 20 layers	10.6GB	5 minutes	0.829

Just changing to batch 1 barely saves anything (35.6 → 33.3GB); most of the memory goes to the weights, gradients and Adam states of the trainable parameters (fp32, 16 bytes per parameter).

macOS doesn’t give all of the memory to the GPU: on this machine torch.mps.recommended_max_memory() is 51.8GB (81%). Extrapolating at the same ratio (on the optimistic side; smaller machines may have a lower ratio and slower chips; none of this was measured):

Machine	Roughly available to GPU	Recommendation	Left over
64GB	52GB	1.7B default	about 13GB
48GB	39GB	1.7B freeze 20 layers (default is right at the limit)	about 21GB
32GB	26GB	1.7B freeze 20 layers	about 8GB
24GB	19GB	0.6B freeze 14 layers	about 7GB
16GB	13GB	0.6B freeze 20 layers	about 2GB

Freezing some layers of 0.6B actually scores a bit higher than the full 0.6B model; each group has only 10 samples, so a difference within ±0.02 is within error, and I haven’t compared 0.6B by ear either.

Deployment

# Convert the chosen epoch to MLX 8bit and put it in the models directory
python -m mlx_audio.convert --hf-path <ckpt>/epoch-8 --mlx-path ~/Models/qwen3-tts/tuned/<id>-e8-8bit -q --q-bits 8

~/.config/ttsd/config.json:

"tuned_voices": {
  "<id>": {"name": "Display name·fine-tuned", "model": "tuned/<id>-e8-8bit", "speaker": "<id>", "gender": "m", "lang": "zh"}
}

speaker must match the --speaker_name used during training. After the change, restart with launchctl kickstart -k gui/$(id -u)/<label>, then use the API to create a temporary script, generate one sentence to verify, and delete the script.

Changes to ttsd: the voice id is tuned:<id>, each fine-tuned voice gets its own model slot; at generation time the language is fixed to auto and no tone is passed; in the web UI it’s under “My Voices”, and the tone box greys out when it’s selected.

Pitfalls

Safari: no sound when I hit play, downloads work fine: the page uses Web Audio for playback. The server and code were both fine; restarting Safari fixed it. There’s currently no error message when playback fails; I could add one later.
ttsd’s safe_id only accepts hex: fine-tuned voice IDs (e.g. English names) are rejected as invalid, and the voice doesn’t appear. I changed it to “must be a key already in the config”; a newly added unit test caught it.
Speaker keys must be in English: the key becomes the speaker ID in the model and the directory name. The open-source version enforces ASCII.
HF download gets stuck at the last step: the file is already downloaded (the size matches) but gets stuck at the checksum and rename step. The temp filename is the sha256 itself; compute it yourself, check that it matches, then mv it into place.
pkill -f killed the wrong process: the match string used to kill the download process also appeared in another background command waiting for the download, so that one got killed too. Killing by PID is safer.
zsh doesn’t split variables on spaces: set -- $var doesn’t split in zsh; write out the loop arguments or use an array.
mlx-audio reads sys.argv: my script passed the model path on the command line, and mlx-audio took it as the model name. I moved it into the script.
Speaker encoder dtype on MPS: when the model is bf16, cast the mel input to the same dtype.
Redacting screenshots: before screenshotting, I renamed things and deleted content showing real people on the page using JS; I re-ran the review page with demo data synthesized from system voices before capturing. When Playwright renders charts, the double quotes in font-family truncate the HTML style="…", so the font reverts to the default serif.

How to reproduce

The shortest path (run.sh / deploy.py added on 2026-10-29; video files can go straight into the assets folder, and non-wav files are decoded with ffmpeg):

cd finetune && cp voiceprep.example.json voiceprep.json   # after filling it in
./run.sh prep                 # slice + transcribe + pick speakers; open the review page when done
./run.sh train alice          # encode → train → sample audio → score; on low memory add --epochs 6 --batch_size 1 --grad_accum 8 --freeze_layers 20
./run.sh review               # /compare/alice to pick a round
./run.sh deploy alice 8 --name "display name" --gender m --restart <ttsd's launchd label>

deploy copies the model into the console’s models_dir/tuned/, backs it up and then edits tuned_voices (the speaker ID is read from the checkpoint), and optionally restarts it. To run it manually, step by step:

cd finetune
cp voiceprep.example.json voiceprep.json      # speaker, reference recording and transcript, material directory
.venv/bin/python prep_data.py
.venv/bin/python review.py                    # 127.0.0.1:18410, no login, only open on the local machine; use ssh -L remotely
.venv-train/bin/python build_train.py alice
.venv-train/bin/python sft.py --train_jsonl <work>/alice/train_with_codes.jsonl --speaker_name alice \
    --output_dir <work>/alice/ckpt --epochs 10 --save_epochs 2,4,6,8,10
#   low memory: --batch_size 1 --grad_accum 8 --freeze_layers 20 [--init_model_path Qwen/Qwen3-TTS-12Hz-0.6B-Base]
../.venv/bin/python gen_samples.py alice
.venv/bin/python score_samples.py alice       # then open /compare/alice and listen

Not verified yet

Actual memory usage and speed on 16GB / 24GB / 32GB machines (all extrapolated from the 64GB peak and 81%).
What the 0.6B fine-tuned version sounds like; the web page currently loads the 1.7B preset/clone models by default. The 0.6B fine-tuned version can convert and generate, but it isn’t live yet.
Whether a few more hours of data would improve it further; how the proportion of clips under 10 seconds affects the accent.

How Much Mac mini Memory? M6 and M5 Pro Buying Guide

Tue, 20 Oct 2026 00:00:00 +0000

What’s the key to choosing a Mac mini? The CPU already crushes everything in its class, and you can add storage yourself later; but the memory is soldered to the motherboard, and how much memory you get is closely tied to what you use it for as a server.

Buy too little and the models you want to run later won’t fit, so you have to replace the machine. Buy too much and you’re using a sledgehammer to crack a nut. And the gap between configurations can be over ¥10,000. If you’re thinking of buying one too: how much memory should you get, which chip, and roughly how much will it cost?

Below, first, the recommended configurations for different uses; the full configuration and price tables are at the end of the article.

Recommendations first

Just a home server, no large models: 16GB. the M6 16GB+512GB is ¥8,499, or a used M4 for ¥3,000–4,000.
Want to try local models: M6 32GB, from ¥9,999. 27B runs but very slowly; MoE models are fast and good enough for writing articles, but overall quality is not as good as dense models.
Want to use 27B daily, long conversations: M5 Pro 48GB, ¥19,749.
Also want to run other services alongside, or want to try larger models later: M5 Pro 64GB, from ¥20,499.
Around ¥20,000 and you care more about speed: base Mac Studio at ¥19,999, cheaper than the mini 64GB but with only 36GB of memory. With a budget of ¥27,000, the Studio 64GB is better value than the mini 64GB.

Once the use is settled, 512GB of storage is enough; 256GB is really too small. You don’t have to go for the bigger capacity all at once — spend what you save on an external drive later, or have a professional service mod the internal drive.

For local models I’ll use the hottest model right now, Qwen3.8-27B, as the example; the engine is oMLX. My machine is an M5 Pro 64GB, which has the most headroom, so I can measure how much memory the model actually uses under different settings. For the other tiers I don’t have the actual machine, so I calculated from the memory peaks I measured; for M6 speed I used publicly available measured results.

Local model memory usage reference

27B 4-bit (Q4) short conversation: peak 17.2GB
27B Q4 up to 160K context: peak about 38GB
27B 8-bit (Q8) short conversation: peak 29.0GB

That’s just the model process itself. macOS itself, the browser and background services also use memory. So subtract the model peak from total memory and see whether the remainder is enough for other programs’ daily use.

When memory runs short, the Mac moves some content to disk (swap), and programs don’t crash right away. It looks like it runs. But I don’t count that as “usable”. Frequent swapping makes the server unstable.

Best option for a personal local server: 16GB

Don’t consider local large models on a 16GB machine. Its role is clear: a local server.

My machine keeps Hermes (an AI assistant; on a 16GB machine it only uses cloud models), Jellyfin (my home media library) and Syncthing (syncing files between several devices) running all the time. 16GB handles these without strain.

Other services that are good to keep running long-term:

Time Machine: other Macs at home back up automatically to this machine. It’s built into the system — just set a folder as the backup destination in Sharing settings. Backups eat disk space, so you’d usually attach an external drive with plenty of capacity.
AdGuard Home: blocks ad and tracking domains at the DNS layer; point your router at it and every device at home is covered. It only blocks by domain, so not all ads get removed.
FreshRSS: your own RSS reader, with read status shared between phone and computer.
Paperless-ngx: scan contracts, invoices and manuals into it, it OCRs them automatically, and later you can find the original just by searching the text. When you import a big batch of old files at once, OCR has a spike.

FreshRSS and Paperless-ngx usually run in Docker, which means spinning up an extra Linux virtual machine. Docker Desktop’s default memory limit for it is half the host, so 8GB on a 16GB machine. So add things one at a time, and stagger tasks with spikes like OCR and video transcoding.

The chip doesn’t matter at this tier. The M6 16GB has 153GB/s of bandwidth, a bit lower than the 170GB/s of the 24GB and 32GB models, but as a server you won’t need that difference. A used M4 is fine too.

Since you’re giving up local large models, this tier suits clear-headed people who’ve committed to cloud models. You get top-tier cloud models plus a personal server that responds 24/7, and save a lot of money.

Worth noting: although the base M6 is ¥2,500 more than the M4’s ¥4,499 back then, this 2nm chip is genuinely impressive.

Local models: M6 32GB

Memory first. 27B Q4 short conversation peaks at 17.2GB, leaving 14.8GB out of 32GB. It fits. At 160K it needs about 38GB, already more than total memory, so context has to be kept short (estimated).

Now speed. For every token the model outputs, it roughly has to read the weights from memory once, so output speed is heavily tied to memory bandwidth. The M6 is 170GB/s and the M5 Pro 307GB/s, a 1.8x difference.

I don’t have an M6, so I looked up other people’s measurements, all on 32GB models running Qwen3.8-27B 4-bit:

A German user’s public test on GitHub (LM Studio, GGUF format): 11–12 tokens per second writing English and German paragraphs, 17.5 writing code
A video review (using MLX directly): 8–9 per second

Mine writes 300 characters at 25.9 per second. The engines and formats differ, so it’s not a strict comparison, but the gap is over 2x, larger than the bandwidth difference. The M6 has only a 12-core GPU versus 20 cores on mine, which may also matter (my guess).

At around 10 per second, asking a few questions occasionally is fine, but as a daily driver it’s on the slow side. So 27B on the M6 32GB is limited to just being able to run. For daily use it’s basically a no-go.

If you want speed on the M6, switch to an MoE model. An MoE model has a large total parameter count, but each output token uses only a small part of it, so fewer weights are read and the bandwidth requirement is much lower.

Take the 4-bit version of Qwen3.6-35B-A3B. There are two other people’s measurements on the M6 32GB; I also ran the same model’s 4-bit version on my machine with oMLX, using the same prompt types and parameters as the GitHub test:

Short inputs (German, English, code, JSON): M6 63–69 tokens per second, mine about 110, 1.6–1.7x the M6
After reading in about 20,000 tokens of material: M6 outputs 58.5 per second, mine 80.4; reading speed M6 1,215 per second, mine 2,176

Bandwidth differs by 1.8x, and the short-input speed difference is close to that.

Memory measurements on my machine:

Short input: peak about 21.5GB
Reading 20,000 tokens: about 23.7GB
Reading 65,000 tokens: about 24.7GB
Reading 130,000 tokens: about 27.0GB

No swap was used at any point. MoE memory grows very slowly when reading long material. Subtracting from 32GB (estimated): about 10GB left for short input, about 8GB at 20,000 tokens, only 5GB at 130,000 tokens. The user in Japan reported 19.7GB, lower than what I measured, possibly because of a different counting method.

So an M6 32GB running MoE 4-bit can read long material too, leaving 8–10GB for the system — enough for a browser and everyday office work. But you can only run this one model; running Docker, a media library and similar services at the same time probably means staggering them.

Of course MoE has a cost. On my mini it does about 110 tokens per second, 3–4x the 27B; but 35B-A3B activates only about 3B parameters per token, so quality is a bit worse than the 27B. My worry is that it keeps putting out low-quality content, and cleaning up after it is harder work. So I still use 27B day to day. If speed matters more to you, MoE is still the first choice on a Mac.

Another option is the M5 Pro 24GB at ¥12,999. The chip is faster, but it has 8GB less memory than the M6 32GB; 27B Q4 short conversation leaves 6.8GB, which gets tight once you open a few programs. Looking only at local models, this tier is a bit awkward.

Using 27B every day: M5 Pro 48GB and up

If you use local large models every day, you’ll inevitably have long conversations and feed in long documents. Then memory has to be sized for 160K:

48GB: at 160K about 10GB left for the system and other programs — it runs, but it’s not roomy
64GB: about 26GB left (measured peak on my machine)

All M5 Pro tiers have 307GB/s of bandwidth, so the 48GB model’s output speed should be close to mine: 35.8 tokens per second answering “hello”, 25.9 per second writing 300 characters (the 48GB figure is estimated).

Running MoE 4-bit is roomy too: reading 130,000 tokens peaks at about 27GB, leaving 21GB of 48GB.

Running other services at the same time: 64GB

This is my configuration: M5 Pro, 18-core CPU / 20-core GPU, 64GB of memory. It keeps Hermes, Jellyfin and local video generation with MiniMax H3 running at the same time.

I set a 48GB cap on the model process, leaving 16GB for the system and other services. Even so, the model and H3 can’t run at the same time. The model is about 38GB and H3 about 22GB, roughly 60GB together, leaving too little headroom for the system. I’ve tested it; they have to be staggered.

So 64GB doesn’t mean everything can run at once either. Run them staggered and everything fits.

Why did I buy 64GB? When I buy a machine I plan to use it for a long time, and memory can’t be changed.

Apple’s ecosystem is moving fast on AI, and many local models — text, image, video, voice generation — are all heading toward compressing size as much as possible while keeping quality. The more memory, the better your ticket in. It also has to run everyday tasks, and I don’t want memory maxing out and swapping often, because then the server becomes unstable and can’t be called a server anymore.

Around ¥20,000: Mac mini or Mac Studio

At the ¥20,000 price point, the Mac Studio and the Mac mini cost the same:

Mac mini M5 Pro 48GB+1TB: ¥19,749, bandwidth 307GB/s
Mac Studio M5 Max 36GB+512GB: ¥19,999, bandwidth 460GB/s
Mac mini M5 Pro 64GB+512GB: ¥20,499, bandwidth 307GB/s

The base Studio is ¥500 cheaper than the 64GB mini. It trades away part of the memory for a Max chip: 1.5x the bandwidth, but only 36GB of memory. Running a 27B Q4 model for short conversations leaves 18.8GB free, and it should be faster than mine, but a 160K chat needs about 38GB, which won’t fit. So if you have long conversations every day, the 48GB or 64GB mini is still the right choice; if it’s mostly short questions and answers and you want it a bit faster, the base Studio is the better deal.

Move up in budget and the difference becomes clearer:

Mac mini M5 Pro 64GB+1TB: ¥22,749, bandwidth 307GB/s
Mac mini M5 Pro 64GB+2TB: ¥27,999, bandwidth 307GB/s
Mac Studio M5 Max 64GB+512GB: ¥27,499, 40-core GPU, bandwidth 614GB/s
Mac Studio M5 Max 128GB+512GB: ¥39,499, bandwidth 614GB/s

For the same 64GB+512GB configuration, the Studio costs ¥7,000 more than the mini, in exchange for 2x the bandwidth and better cooling. Compared with the 64GB+2TB mini, it’s ¥500 cheaper with 2x the bandwidth, except that the drive is 1.5TB smaller. You can add storage externally, but you can’t add bandwidth. If your budget reaches ¥27,000 and it’s mainly for local models, the 64GB Studio is the better value.

Thinking about it now, if size weren’t a concern, maybe the 128GB Studio would also be the better choice, with better cooling and more headroom. Apple’s own chips keep moving forward too, and I’d guess that if you’re willing to wait, later chips will most likely be better suited to local models. But all of that is the cost of waiting. Life is a hundred years at most; rather than waiting and waiting, it’s better to buy early and start enjoying it sooner.

Of course, my situation isn’t just about using local large models — cloud models are always more tempting. Unless you’re clear that local models are fully up to your local work, it’s best not to kid yourself that buying a Mac mini means you can leave cloud models behind for good.

Storage: just enough, add external later

Storage, unlike memory, can be added later. Once your use is settled, just pick enough built-in storage.

Running local models needs spare space. If it’s only a server, 512GB is enough; put video, audio and backups on an external drive. 256GB is really too small — the system alone eats a big chunk. If you buy 256GB, I’d suggest just modding the internal drive; internal drives are more stable than external ones. Modding means going to a specialist shop and may affect the official warranty. I think going straight to 512GB is safer.

Upgrading storage on the official site isn’t cheap: on the M6 32GB, going from 256GB to 1TB costs ¥3,750 more; on the M5 Pro 64GB, going from 1TB to 2TB costs ¥5,250 more. You can save that money for now and buy an external drive later as needed. I chose 2TB because I have to back up a lot of video in my daily work. For just running models and being a server, you don’t really need 2TB.

Configuration and price tables

Prices are official China prices from October 2026, not counting Double 11 promotions. The M4 is no longer sold on the official site, so the price listed is a used price from Xianyu (China’s second-hand marketplace).

Earlier tests on this Mac mini:

“Mac mini pocket rocket runs 27B, up to 35 token/s”: how to set up local large models and how fast they run
“Mac mini runs AI video: how much memory it uses and how long generation takes”: running MiniMax H3 locally to generate video
“Keeping files in sync between two computers, without using my iCloud space”: the Syncthing mentioned in the 16GB tier

If you have an M6 32GB, an M5 Pro 48GB or a Mac Studio, feel free to leave your measured speeds in the comments. If there’s anything else you’d like me to test on this mini, leave a comment too. Hope this helps.

Sources:

Data for my machine: measured on my Mac mini M5 Pro 64GB, oMLX running Qwen3.8-27B, see the previous post “Mac mini pocket rocket runs 27B, up to 35 token/s”
Mac mini and Mac Studio bandwidth and configurations: apple.com.cn/mac-mini/specs, apple.com.cn/mac-studio/specs
M6 32GB running 27B (LM Studio, GGUF): github.com/HDZucht/Mac-Mini-M6-LLM-benchmarks
M6 32GB running 27B (MLX, video review): youtube.com/watch?v=7ugFOo8e8H4
M6 32GB running MoE: github.com/HDZucht/Mac-Mini-M6-LLM-benchmarks, note.com/corestudio/n/n583c1b00f8ef
M5 Pro running MoE 4-bit: measured on my machine with oMLX 0.7.0, model mlx-community/Qwen3.6-35B-A3B-4bit (October 20, 2026)
M6 2nm, from ¥6,999: reports from the August 25, 2026 launch event (ITHome, Sina Tech); M4 Mac mini, from ¥4,499 in China: 2024 launch price (ITHome)
Services on the 16GB server: official documentation for Docker, AdGuard Home, FreshRSS and Paperless-ngx

Mac mini Runs a 27B Model at Up to 35 token/s

Sat, 17 Oct 2026 00:00:00 +0000

After using cloud AI for a while, one thing has kept distracting me: quota. There’s a cap every 5 hours, and another every week. Halfway through a task, it says I’m out of quota and I just have to wait. Pretty annoying. It also gets stuck when the network is bad. And there are some questions I’d rather not send to the cloud, but I had no other way.

So this time I seriously tried running a local large model on my Mac mini at home. I was after two things: token freedom — use as much as I want — and no censorship, fewer refusals.

I spent three days testing it. It works, and it can run 24/7. Once a conversation reaches 130k tokens, a reply still comes in 3–4 seconds. When the cloud quota runs out, it takes over automatically.

Below: how to configure it, how the settings differ, and if you’re thinking of buying one, how to choose memory.

My machine and how I use it

Mac mini, M5 Pro, 20-core GPU, 64GB memory, 2TB disk. It’s normally the home server and also runs an AI assistant, a media library and video generation, so the model can’t take up all the memory. So I set a 48GB cap on the model process; if it goes over, it stops.

The model is Qwen3.8-27B, a 27-billion-parameter model. I tried two engines, oMLX and MTPLX, and kept oMLX.

How fast it actually runs

Here’s what daily use feels like:

Scenario	How long you wait
Already 130k tokens into a chat, ask one more thing	3–4 seconds to start answering
Chat at 210k tokens	4–7 seconds
Feeding in 10k+ characters of new material at once	Tens of seconds to over a minute
Output speed	20–27 tokens per second, short answers up to 35.8

While writing this, I opened oMLX’s built-in web chat and tested again. A one-line “hello” reply came at 35.8 tokens per second, the fastest I’ve seen; asking it to write a ~300-character intro gave 25.9 tokens per second, 10.2 seconds total from sending to finishing.

Peak memory for the whole process was about 38GB, and it didn’t use swap. After a service restart, the previous conversation cache was still there, so I could keep chatting without re-reading.

This speed is usable for everyday work. It depends on one setting: prefix caching.

The most important setting: prefix caching

With caching off, every question makes the model read the entire history from the beginning. Once the chat reaches 60k tokens, each question takes 2–3 minutes. In my first round of testing, I measured “how long it takes to read in 260k tokens at once.” The first token took 18 minutes — I almost concluded that long local conversations were unusable.

With caching on, it only reads the new part. That’s where the 3–4 seconds come from.

Caching matters more than changing quantization or turning on acceleration. That was my biggest takeaway this time. I put the cache on the SSD, capped at 100GB, which holds about four or five long conversations at full length.

How the settings differ

4-bit is enough

The model can be compressed to different precisions; the fewer bits, the less memory it uses. I compared 4-bit (Q4) and 8-bit (Q8) on 63 questions:

	Structured questions	Code	Peak memory (short chat)
Q8	30/42	8/8	29.0GB
Q4	34/42	7/8	17.2GB

Q4 is no worse than Q8. It got one fewer code question right; tool calling is 3/3 for both. Reading in 260k tokens at once, Q4 reads 237 tokens per second with a 36.1GB peak; Q8 reads 160 per second with a 45.4GB peak. oMLX has dedicated acceleration for 4-bit, so Q4 is both faster and uses less memory. I also let Q4 run continuously for two hours: 13 questions all correct, memory steady at 36GB.

Uncensored version: same capability, benefit not measured

I compressed both the uncensored and official versions to Q4. On the same set of questions, scores were almost identical, and speed was about the same too (16.61 and 16.70 tokens per second).

But on the few sensitive questions I prepared, both versions answered normally, so I couldn’t measure how much the uncensored version actually helps this time. According to the model author’s notes, it “reduces refusals” rather than “never refuses”; with thinking mode on, about 8.7% still get refused.

MoE model: fast, but memory-hungry

I also tried a 35B MoE model. It only uses 3B parameters at a time, so it’s fast: 56 tokens per second output on short chats, 3–4 times the config above. But the 8-bit version’s weights alone take about 35GB, peak hit 47GB, and long conversations were unstable. On a 64GB machine, I ruled it out.

The config to copy

Engine: oMLX 0.7.0; model: Qwen3.8-27B uncensored 4-bit. Below, each row gives the setting and how to write it in oMLX:

Item	Setting	In oMLX
Prefix cache	On, on SSD, 100GB cap	Startup args `--paged-ssd-cache-dir`, `--paged-ssd-cache-max-size 100GB`
MTP acceleration	On	Model setting `mtp_enabled: true`
Thinking mode	Off	`enable_thinking: false`
Context window	160K	`max_context_window: 163840`
Memory cap	48GB	Startup arg `--memory-guard-gb 48`
Concurrency	1 request	Startup arg `--max-concurrent-requests 1`
Idle unload	30 minutes	`ttl_seconds: 1800`, reloads in about 4 seconds next time

Two things to watch:

MTP has to be imported first. This 4-bit model’s MTP weights are in a separate file, and oMLX can’t read them by default; you need oMLX’s built-in import function (import_mtplx_sidecar) to sort it out. It modifies the model directory directly, so copy it first with cp -cR. Worth the trouble: at 130k tokens, output went from 10.6 to 26 tokens per second.

4-bit has dedicated read-in acceleration (oQ A8), about 1.4× faster, and I have it on. Q6 and Q8 can’t use it.

I tried these and don’t recommend turning them on:

KV cache quantization: both read-in and output became 2–3 times slower.
ANE prefill: 30% slower instead, uses 16GB more memory, and disables the oQ A8 above.
In-memory hot cache: immediately blows up memory usage.
256K window: it can finish, but it sits right at the 48GB cap with no headroom.

I also hooked it into the AI assistant Hermes as a backup model: when the cloud is rate-limited, out of quota or offline, it switches to local automatically. The cost is that every new conversation’s first message waits about 20 extra seconds, because the assistant always carries a big chunk of instructions, about 14k tokens. After that it’s fast.

Where I use it from

I use the same model from four places. oMLX provides both OpenAI- and Anthropic-format APIs, so common tools can connect. The speed difference isn’t in the model; it’s in how much fixed content each request has to read first:

Entry point	First message of a new chat	Good for
oMLX’s built-in web chat	About 1.4 seconds	Pure chat, writing, questions I don’t want going to the cloud
Hermes (used in WeChat and Feishu)	About 20 seconds	Daily assistant; switches over automatically when the cloud is unavailable
Claude Code	About 35 seconds	Simple coding, when I don’t want code leaving the machine
Codex	About 54 seconds	Same as above

As the same conversation continues, every entry point hits the cache and the gap shrinks. But honestly, the 27B 4-bit model is clearly worse than cloud models at multi-file coding; I only use it for simple work.

It’s also convenient on a laptop. I use Tailscale to access it from my own devices; only my devices can connect, and it works when I’m out.

Can it stay on all the time

Yes. But a few things to know.

Power: inference draws 50–60W more than idle, peaking around 80W. When the model is idle it draws almost nothing extra, and after 30 minutes of no use it unloads automatically. I spend most of my time typing, and at one or two hours of cumulative inference a day, that’s a few dozen kWh more per year.

Temperature: the chip rises to 75–77°C in 1–2 minutes and stays there; no thermal warnings, no throttling.

Disk: writes come mainly from the cache, about 140MB per 1000 tokens of new content. With very heavy use, that’s about 28GB a day, around 10TB a year. Mainstream 2TB SSDs are rated for several hundred TB of writes or more, so ten years is no problem.

Can’t run alongside other big tasks: this machine also runs video generation, peaking around 22GB; add the model’s 38GB and it goes over, so I can only run them at different times.

If you want to buy, how to choose memory

I only tested the 64GB machine. Below, everything except 64GB is extrapolated from measured memory peaks, for reference only; before buying, better to check real-world tests of the same config.

Memory	My judgment
64GB	Measured: 27B 4-bit and 160K long conversations both work, and other services can run alongside; it just can’t run at the same time as big tasks like video generation
48GB	Extrapolated: 27B 4-bit runs, and short chats peak at only 17GB; but when long conversations reach 160K, the model peaks around 38GB, and leaving headroom for the system gets tight, so the context may need to be shortened
32GB	Extrapolated: with 27B 4-bit, short chats are worth a try, but there isn’t much room for long conversations and it’s hard to run other services alongside; a smaller model is more realistic
24GB and below	Extrapolated: the 27B tier isn’t realistic, go straight to a small model

About the new M6 Mac mini: Apple’s published configurations top out at 32GB of memory, so based on the estimates above, it can only fall in the 32GB tier. There are no real tests yet of how much faster the new chip is or whether the engine is optimized for it, so I won’t draw conclusions.

My take: for local large models, memory matters more than chip tier. The chip decides speed; memory decides whether it runs and how long you can chat. Don’t skimp on the disk either; cache and models both take space.

If you mainly use the cloud and occasionally want an unlimited backup that never leaves the machine, a Mac mini with a lot of memory can already do that. I hope these numbers help with your config choice.

Running AI Video on a Mac mini: Memory Use and Generation Time

Fri, 09 Oct 2026 00:00:00 +0000

If you’re planning to buy a Mac mini to run local AI, choosing how much memory to get is probably the hardest part. With video models in particular, the download alone is over a hundred GB, so it’s easy to think the machine needs a hundred GB of memory as well.

I ran a round of MiniMax-H3 tests on my M5 Pro with 64GB at home. In the short-clip tests, memory peaks were mostly in the 18.5–22GB range; the 9-second run reached 25.6GB. With the recommended parameters, generating a vertical video of about 2 seconds takes about 3 minutes.

So this round of short-clip tests doesn’t use all 64GB. But you shouldn’t choose a configuration based only on the 22GB figure either; you also have to account for the system, other software, and the memory available to the GPU. Below I list the results from my actual runs, as a reference for anyone who hasn’t bought a machine yet.

I used h3.c, written by antirez, the author of Redis. It’s pure C + Metal. It supports text-to-video, first/last frame, and reference images, and can generate audio alongside the video.

First, here are two generated samples:

(Blog version: the videos above have been replaced with the original videos with audio; the WeChat Official Account version uses silent GIFs.) The clerk in that clip said “Welcome” correctly, but it doesn’t always go this smoothly — I’ll get to that below.

Memory: you won’t use all 64GB, but you can’t just buy a smaller-memory machine either

Mac mini, M5 Pro, 20-core GPU, 64GB memory, 2TB drive. It also runs other services as usual; I didn’t stop them during testing. You may also be wondering: if you’re only running this model, do you need to buy 64GB?

Here are the records:

Test	Recorded memory peak
~2-second short clip, various acceleration parameters	18.5–22GB
9-second vertical video	25.6GB

These are peaks recorded during generation, not the total usage of the whole machine including the system and other services. These tests didn’t hit swap; 64GB really does leave a fair amount of headroom. Before starting the service, headroom is around 93%; while the service is running, headroom can still stay around 60%.

The downloaded model size and the memory it uses at runtime are not the same number. h3.c loads different parts in stages; the path my M5 uses also converts to int8 at load time. 134GiB of weights sitting on disk doesn’t mean 134GiB of memory is used all at once.

But there’s another number to look at: the program identifies this machine’s recommended GPU working set as 51.8GiB. That’s the amount of memory Metal suggests the GPU should use at once; it doesn’t mean the model is already occupying 51.8GiB, nor does exceeding it mean it definitely can’t run. Macs use unified memory, but you can’t treat the 64GB on the box as space the GPU can freely fill up.

That’s also why I didn’t simply write “24GB is enough.” Short clip peaks are already at 18.5–22GB, and the 9-second run reached 25.6GB; the system and background programs aren’t counted yet. If you switch to a smaller-memory machine, you’d need to re-test whether this same set of parameters still has headroom.

If I were choosing memory for this use case now, I’d think about it like this:

Memory configuration	How to think about it based on this test	Actually tested
24GB	Short clip peaks are already close to the machine’s total memory, and the 9-second run exceeds it; you can’t just reuse this set of parameters, you’d need to test a memory-saving approach	No
48GB	More headroom than these peaks; worth considering if you mainly do short shots and don’t run many programs at once	No, inferred from this machine’s records
64GB	I also keep other services running; these tests didn’t hit swap, and it’s fairly hassle-free	Yes, this is the machine in this article

The original report’s estimate for 48GB assumes the GPU working set is about 80% of memory, roughly 38GB. That ratio is only an estimate and can’t be treated as a fixed quota for every machine; if you buy a different configuration, you still have to look at the number the program actually reports. I also haven’t run this on 48GB, so what I’m saying here is “worth considering,” not a guarantee that it’s as fast as 64GB.

There’s another path for small memory, but it trades time for space. h3.c’s --ssd-streaming reads later parts of the main model from the SSD while computing. The author recorded the main model tensor storage on an M5 Max dropping to about 2.0–2.1GiB; note this isn’t the whole program using only 2GB — text encoding, video decoding, the system and other buffers still need memory.

In the author’s tests, one round of main model computation was 26% and 84% slower, respectively, for the two aspect ratios, using the same BF16 path. That can’t be directly converted into “how many minutes a 24GB Mac mini would wait in total,” nor can it be applied to my int8 tests here. I didn’t test streaming this time, so I won’t give that answer yet.

So the value of 64GB is headroom; you can’t call it a must based on these few short clips alone. If I were mainly running H3 short clips, I’d consider 48GB first; if I also wanted to run other models and services at the same time, I’d rather go with 64GB. For 24GB, you’d first have to test a memory-saving approach before deciding whether its speed is acceptable.

What about the M6 Mac mini everyone’s discussing now? Apple’s published configurations top out at 32GB unified memory; you can’t choose the 48GB or 64GB mentioned above. Compared with this test’s 18.5–22GB short clip peaks, 32GB looks worth trying; but the 9-second run already hits 25.6GB, and you still need to leave space for the system and other programs, so you can’t conclude it will definitely run just because “32 is bigger than 25.6.” If you have an M6, feel free to leave your test results in the comments.

There’s also software compatibility. As of this update, h3.c’s public documentation still focuses mainly on optimizing for M3 Max and M5 Max, and doesn’t list M6-specific optimizations or measured results. I’m also using the M5 acceleration path here; you can’t directly apply this machine’s roughly three-minute result just because M6 is newer.

So if I were buying an M6 mainly for H3, I’d first wait for its support status and measured results on the same configuration; if I also needed to do other things and H3 was just for occasional fun, I’d keep it on the candidate list. I don’t have an M6, so for now I won’t make up an estimated time for it.

Once memory is enough, the next question is whether you can live with it day to day: how long does generating a video take?

Generation speed: fine for short shots, long clips mean a wait

All of the following are actual records from this machine, portrait 576×1024, recommended quality:

Requested duration	Total time
2 seconds	2 min 40 s
3 seconds	3 min 35 s
5 seconds	7 min 24 s
9 seconds	17 min 20 s

The program rounds the frame count up, so the actual video is slightly longer than requested. The time is measured from when the run starts to when the output file is written, including model loading, generation, and decoding.

The 2- and 3-second clips are acceptable—enough for a short shot. Beyond that, the wait gets long. I initially estimated from two data points that 9 seconds would take about 12 minutes; it ended up taking 17. I didn’t test 15 seconds, and I don’t usually need clips that long.

The h3.c version used in this article is 8974cc0; testing was from late September to early October.

Recommended mode and draft mode

With the same image, same prompt and seed, I tested several acceleration methods. For a 2.33-second portrait video:

Default parameters: 433 seconds.
--layers 45 --core-reuse 4: 188 seconds.
Internal size lowered to 288×512, with the previous parameters: 59 seconds.

Comparing face crops at original size, I could barely tell the second set from the default, so I made it the recommended mode.

The third set has visibly softer detail, but the composition and motion are basically unchanged, so you can first check whether the direction is right. A draft is one version per minute; once you’re happy, rerun it with the recommended mode.

The “one minute” and “can’t see a difference” both come from this set of material; with other material, you’ll still need to check for yourself.

If you first try the direction with a draft and only rerun the recommended mode once you’re satisfied, you don’t have to wait three minutes every time. But after saving memory and cutting down the wait, there’s one more thing you can’t skip: disk space.

Disk space counts too

The whole repository on Hugging Face is 464GiB, but you don’t actually need to download all of it locally. h3.c doesn’t use the weights in the root directory.

Text-to-video and first/last frame need FL2VA, 134GiB; reference images need Ref2VA, also 134GiB. I later compared the files and found that the text encoder, VAE, and other files are identical on both sides; only the main video model differs. By reusing the identical files with APFS clones, you only need to download another 62GiB.

If you want both text-to-video and reference images, with this reuse approach the models themselves take up about 196GiB. That doesn’t include the system, software, input assets, and generated files. If you only run text-to-video, you can download just the 134GiB set first; you don’t need to install every feature from the start.

If you’re downloading in China, you can use MiniMax’s official repository of the same name on ModelScope; I measured 73MB/s here, and 134GiB downloaded in half an hour.

The machine can run it, but the results are another matter. The GIFs above show successful results; the failures below say more about what to watch for in real use.

Dialogue has to be written in the right format

The first time I wrote a prompt, I mixed the dialogue into a descriptive paragraph, and the character’s lines came out as vague syllables that sounded like Japanese but weren’t.

Later I followed the format and put the dialogue in separately:

<d>[Chinese] 欢迎光临！</d>

And marked the speaker (S1); only then was it normal.

I also specifically compared having the program assemble the prompt directly versus having AI expand it. In the bakery scene, the program-assembled prompt also got it right, and the description could be in Chinese or English. The AI version wrote a long paragraph but added a line of subtitles at the start. So now I have the program assemble it by default, and only turn on AI expansion when I need a more detailed shot description.

I also tried a real person: “国庆快乐” (Happy National Day) came out as “国供快乐”. The animated clerk segment worked, but that doesn’t mean real-person dialogue is stable; this still needs more testing.

Reference image mode

If you’ve used minimax h3, you know it has 3 modes: text-to-video, image-to-video, and first/last-frame video.

Text-to-video and first/last-frame video are easy to understand, but image-to-video needs reference images. Supplying the reference images and writing the description still take some skill.

I supplied a character image and a snowy pine forest, wanting the girl to walk into the forest and introduce the environment. The assets were these:

Sometimes the result still started in the bakery; sometimes the whole video was the solid background from the character image, and the pine forest wasn’t used at all.

Later I added one sentence: take only the character from the character image, and don’t include the background. With the same four combinations, two of them failed without this sentence; with it, all four were correct.

The motion was the same. “Slowly walk into the forest, introduce the environment” — I tested it 6 times and never got both the visuals and dialogue right. I changed it to “walk in from the left, stop, introduce this place” — all 4 were correct.

You also need to state clearly what each image is. In this set of tests, specific English nouns plus a trait worked reliably; Chinese definitions and vague “person”, “place” didn’t work well.

These tests used the same material and two seeds, with only a few tries for each phrasing, so don’t treat the success rates here as a guarantee. If you want to try it yourself, use a clean background for the character image where possible, and don’t put eye-catching people or animals in the scene image; generate a draft first to see how it looks.

My own WebUI is now open source

I packaged it as a service: the web UI, the command line, and chats in WeChat and Feishu (a Chinese workplace chat app) all share one task queue.

In the web UI, you enter the description and dialogue, choose the aspect ratio and quality, and submit. For each reference image, you enter its purpose, what it is, and its features, and the program assembles the format. If there’s a scene image, it automatically adds the line above “for other images, take only the subject, not the background”.

Now, in a chat, I can say “the girl in the image waves and says welcome, 3 seconds”, attach the image, and get the video when generation finishes. The service shuts down automatically after an hour of inactivity.

I cleaned up the web UI and queue and open-sourced them as h3-studio (stars welcome):

https://github.com/shisaq/h3-studio

Translation, AI expansion and chat push are all optional plugins. Video generation runs locally; if you choose cloud translation or Codex expansion, the relevant text and images will still be sent out. If you want everything local, choose local translation and leave expansion off.

For now I’ll keep using it for 2–5-second short shots, to make illustrations move, or to test an idea first. Long videos mean a long wait, and the dialogue isn’t reliable enough to skip checking.

If you haven’t bought a Mac mini yet, you can look at these results and think about what you’ll use it for: whether you’ll mainly generate two- or three-second clips or often produce long videos, and whether you’ll run only H3 or also run other models and services. The former is already workable for me; for the latter, you need to allow for more waiting time and leave more resource headroom.

I tested this on an M5 Pro 64GB, and the speeds here can’t be applied directly to other chips or memory configurations. What this article offers is this machine’s actual output, its resource usage, and its timings. When buying, besides memory, don’t overlook the disk: model downloads aren’t small, and generated videos will keep taking up space too.

Summary

A local model is certainly not as capable as a cloud model, and MiniMax is of course no exception — it can’t compare with a model like Jimeng (ByteDance’s AI image and video generator). And to run a local model, a base-spec Mac mini certainly isn’t enough either. But it has 2 advantages: 1) you never have to worry about credits or token usage again; 2) strong privacy.

This post is just me sharing what I tested; I hope it’s useful as a reference. Feel free to comment and discuss below.

Logic Pro Smart Tempo: Matching Non-Standard Recorded Material

Sun, 12 Jul 2026 00:00:00 +0000

In Logic Pro, to make the software’s grid and beats follow exactly a song you recorded with a non-standard tempo (free tempo / recorded without a metronome), the core idea is to let the software adapt to your audio (let the grid follow the audio) rather than forcing your audio straight.

The quickest and smartest solution is to use Logic Pro’s Smart Tempo feature, which can analyze the downbeats in the audio and automatically generate a fluctuating tempo track to match your recording. If you need more precise manual fine-tuning, use Beat Mapping. Here are the steps:

Import the audio: Drag the audio file you recorded onto an empty audio track in Logic Pro.
Trim the start: Cut off the extra empty space at the front of the audio and align the audio’s start point with the start of the grid (for example, beat 1 of bar 1).
Set the follow mode: Double-click the audio region to open the editor, click the Smart Tempo tab, then click Analyze.

Switch to Adapt: In the tempo display area at the top of the LCD (or in the Smart Tempo project settings), change the Project Tempo Mode from “Keep” to Adapt.

Apply to the project: Right-click the audio region and choose Tempo -> Apply Region Tempo to Project Tempo. Logic will automatically analyze your recording and build a dedicated tempo track for it (the Tempo Map).

Turn on the metronome and have a listen. The metronome will now speed up and slow down along with your recording, matching it perfectly.

When AI Mistakes a Bird Outside the Window for a Sloth: Tuning a Raspberry Pi Birding Camera

Wed, 03 Jun 2026 00:00:00 +0000

I live on the 4th floor, and birds often come and perch outside the window. Sometimes they stay just a few seconds, sometimes they hop back and forth along the railing. I’ve loved watching animal documentaries since I was a kid, and now my kid has inherited that gene too. We both want to know when these birds come and how many times they show up.

So I dug out a Google AIY Vision Kit that had been gathering dust for a long time: a Raspberry Pi Zero, a Vision Bonnet, and a Raspberry Pi camera. It’s the vision version of that 2017 wave of “cardboard-box AI kits,” with a vision processing chip on the board that can run image classification locally.

The goal was simple: sit quietly watching the window at low power, and when something lands in the designated area, automatically record a 10-second video; when I open the browser, I can see the live feed, recent recognition results, and the list of recordings.

Here’s what it looks like now:

Here’s what it can do now:

When a living thing lands in the windowsill area, automatically record a 10-second 1080p video;
Keep only the most recent 30 recordings, deleting old ones automatically;
The web page shows the live feed, current recognition status, recent events, and the recording list;
The recognition log keeps the most recent 1000 entries, and they survive a restart;
You can preview recordings right on the page, or download them;
All inference runs locally, without depending on any cloud service.

The azure-winged magpie below is one it caught itself.

The hardware isn’t new, but it’s just enough

This hardware is very old:

A Raspberry Pi Zero, which is very slow;
A Google AIY Vision Bonnet that runs the vision model;
A Raspberry Pi camera, pressed up against the window glass, looking outside;
The OS is still an old image from around 2017.

Back then, Google made several kinds of models for the Vision Kit. The official introduction mentioned demos such as MobileNets object recognition, expression recognition, and person/cat/dog detection; the AIY models page also lists the model types the Vision Kit supports. In my image, the one that actually runs reliably is a general ImageNet 1000-class classification model based on MobileNet.

I originally wanted to use a model related to the iNaturalist dataset, since it’s better suited to nature observation — it’s aimed at real-world photos of plants and animals. Unfortunately, the toolchain for this old image and old Bonnet is too old, and after all the fiddling I ended up back with the general classification model.

That also determined the story that follows: the old model isn’t very good at recognizing birds — but that same trait is what makes the results more fun later.

First, make the camera take it easy

A single Pi Zero doing live streaming, recording, and AI inference at the same time will easily bring itself to its knees. My approach is to split the tasks:

When idle:
  Run only one 640x360 low-bitrate H.264 stream, using motion vectors to judge whether the ROI has movement

When there's movement:
  Capture one 1080p original frame
  Crop out the windowsill/landing area
  Throw it to the Vision Bonnet for classification

When it's judged that recording is needed:
  Exclusively occupy the camera to record 10 seconds of 1080p
  Package it into mp4 with ffmpeg
  Return to idle detection

When someone opens the web page:
  Temporarily open one 384x216 MJPEG preview
  Close it when nobody's watching

Detection and preview are two separate paths. The live feed on the web page is very blurry, but what’s actually fed to the model is a crop of the 1080p original frame. That matters, because at first I also assumed the problem was the poor quality of the live feed.

The core detection logic is roughly like this:

camera.capture(buf, format='jpeg', use_video_port=True, splitter_port=0)
crop = Image.open(buf).crop(ROI)
classes = image_classification.get_classes(inf.run(crop), max_num_objects=5)

The web page is just a viewing window; it isn’t part of the decision. The decision is made on the cropped landing area.

It really did mistake a bird for a sloth

Now for the most interesting part.

At first I used a very intuitive rule: if a bird word appears in the model output, like junco, sparrow, magpie, and the confidence exceeds the threshold, then record.

In practice it worked badly. Later I went through the logs and found that the labels were very consistent, both for empty scenes and for scenes with a bird:

Scene	Common top judgments from the model
Empty railing	`handrail`, `bannister`, `worm fence`
Glass / window screen / reflection	`mosquito net`, `window screen`
Bird landed	`capuchin`, `langur`, `squirrel monkey`, `hog`, `orangutan`

In other words, it often mistakes birds for monkeys, pigs, and orangutans — if these animals really appeared outside my 4th-floor window in Beijing, I’d definitely be dreaming, haha.

But if I changed the question to “is this still an empty railing?”, it turned out to be very stable.

So I changed the logic to this:

STRUCTURE_WORDS = {
    'bannister', 'handrail', 'fence', 'window', 'screen',
    'mosquito', 'net', 'grille', 'picket', 'pole'
}

def is_structure(label):
    return bool(tokens(label) & STRUCTURE_WORDS)

occupied = top_score >= floor and not is_structure(top_label)

if bird_word_hit or occupied:
    record_clip()

This is the real turning point of the whole system. It doesn’t need to recognize “this is an azure-winged magpie.” It only needs to notice “this area no longer looks like the usual empty railing,” and I record it.

It sounds a bit off, but it works well in practice. Missing a clip is a permanent loss; a false trigger at most means I skip one clip when I’m going through them. For a birding camera, I’d rather err on the side of recording too much.

Put the AI’s judgment on the web page

Tuning used to be painful because all I had was the logs. Once I hooked the live status and the history onto the web page, tuning got a lot easier.

This is a concept image I had AI generate first, to set the direction for the dashboard: dark theme, image first, status concentrated on the right side.

The final page didn’t copy the fake data and decorations from the concept image; it kept only the information structure: the live feed on the left, and on the right the current status, confidence, time-of-day profile, quick links, and recent events.

The live status falls into three categories:

Green “bird”: the model actually listed a bird name among its candidates;
Yellow “living thing?”: the model didn’t report a bird, but the top label doesn’t look like an empty railing;
Gray “no bird”: still an empty scene, like a railing, a window screen, or a reflection.

The old version of the page was plainer, but you could already see this idea:

The log page is another key piece of the puzzle. It refreshes every 2 seconds and lists recent recognition events. Later I also changed the log from an in-memory ring buffer to a JSONL file on disk, keeping at most 1000 entries. That way the tuning context is still there after the service restarts.

The recordings page: first you can watch, then you can download

At first the recordings page was just a list of file names. Later I turned it into a card-style clip library: each video can be previewed directly, with the time, recognition summary, and a download button shown below.

Only the most recent 30 recordings are kept. Each time a new recording is written, the program deletes older files by modification time; it also cleans up once when the service starts. So a restart doesn’t affect this limit.

Adjusting sensitivity by time of day

Birds don’t show up evenly through the day. They’re more active at dawn and dusk, and at night it’s basically noise. So I gave it a simple time-of-day profile:

PROFILES = {
    'dawn':  (0.08, 5,  'high activity at dawn'),
    'dusk':  (0.08, 5,  'high activity at dusk'),
    'day':   (0.12, 8,  'normal daytime'),
    'night': (0.22, 15, 'conservative at night'),
}

At dawn and dusk the threshold is a bit lower and the cooldown a bit shorter; at night the threshold is higher, so wind moving the curtain or glass reflections don’t set off recordings. This strategy is pretty crude, but it fits how I actually use it.

If you want to build one too

This approach doesn’t have to use the AIY Vision Kit. Any “Raspberry Pi + camera + a model that can run classification or detection” can replicate it. The only difference is whether inference runs locally or is thrown to another device or the cloud.

I think the key isn’t how powerful the model is, but these few things:

First determine a fixed ROI. Don’t look for targets across the whole frame; just watch a small area like a feeder, railing, or nest entrance.
Use cheap motion detection when idle; don’t run the model all the time.
When there’s movement, capture a high-definition frame, crop the ROI, and run classification.
Don’t rush to ask “is it a bird.” First collect what empty scenes get recognized as, then change the rule to “does it still look like an empty scene.”
Display the model output. Web page, logs, JSON, anything — don’t tune blind.
Separate recording and live streaming. The preview can be blurry; the recording needs to be clear.
Set a limit on storage. Mine is 30 recordings and 1000 log entries.

Right now this program is just one Python file plus a long-running service, with no database, no cloud account, and no complicated frontend. It isn’t smart, but every morning it can tell me whether anything came to the window last night.

It still calls birds sloths. My kid’s English is better than mine, and she caught on right away; I had to ask her to translate it for me before I got it~

But anyway, detecting something alive is usually good news.

Youke Lili, adding a little sunshine to your life~

Building a "Sleepy" Timer for the AC: Home Assistant + HomeKit Field Notes

Wed, 03 Jun 2026 00:00:00 +0000

Summer’s here. When I sleep with the AC on at night, there are two things I dread most: one is running it all night, waking up with my nose stinging from the cold and the meter spinning merrily; the other is wanting to set a timer to turn it off, but this AC of mine has no timer-off function of its own.

The manufacturer’s mini-program does have a timer — but picture the scene: you’re already lying in bed, and you still have to fumble in the dark to unlock your phone, open the mini-program, wait for it to connect to the cloud, tap in and set the timer… and any sleepiness is gone. What I want is lying in bed, flicking something in Apple Home or talking to Siri, telling it “turn off in X hours”, then closing my eyes with peace of mind.

This article records the whole process of building this “sleepy timer.” In the end it’s very simple, but along the way I hit several invisible walls — and those walls are exactly the most valuable part of this piece. If you’re also fiddling with Home Assistant hooked up to an AC, these pitfalls can save you two evenings of detours.

First, the final result

In Apple Home, there’s now a slider control called “Skylight AC Timer.”

Drag it while lying in bed: drag to 30% = turn off in 3 hours, 25% = 2.5 hours, in 0.5-hour steps;
To cancel: drag it back to 0 / turn it off;
There’s also a fallback: if I set it and then forget, or fall asleep without setting anything at all, at 23:00 it decides on its own — if the AC is still on, it gives another 3 hours, and turns off automatically in the early morning;
It only controls the one in the bedroom; daytime AC use is completely unaffected, and it will never turn off your daytime AC for no reason.

The whole chain looks like this:

Apple Home / Siri
      ↓  drag slider / voice
HomeKit bridge (built into Home Assistant)
      ↓
fan.skylight_ac_timer   ← a "fan shell" slider (hold on, I'll explain below why it's a fan)
      ↓  percentage ÷ 10 = hours
input_number.skylight_ac_hours   ← where "how many hours" is actually stored
      ↓
timer.skylight_ac_manual   ← countdown
      ↓  when time's up
climate.turn_off → bedroom AC (controlled over the local LAN)

Looks unremarkable, right? But “why on earth a fan” and “why not just use the AC’s own timer” — behind these two questions is a whole night of detective work.

Breaking down the requirements first

Before I started, I broke the vague wish in my head into five hard requirements. This step is especially important — it helps you judge whether each approach “actually works”:

Manual, any duration: tonight I might want 2 hours, tomorrow 3 — I have to be able to set it myself.
Fallback safety net: people forget things. If I fall asleep without setting anything, there still has to be a safety net to turn it off.
Only one bedroom: there are two ACs at home; the other one must not be touched.
No collateral damage during the day: running the AC during the day is normal use; the timer logic must never turn it off during the day.
Operable lying down: ideally right in Apple Home / Siri, without opening a third app.

With these five, off we go.

The first bend: can the Home app do timers itself?

The most natural idea: doesn’t Apple Home do automations? Just set an automation to “turn off in X hours,” right?

No. Apple Home’s automation triggers are limited to a few kinds (time, accessory state, someone arriving/leaving, sensors). It has no native “countdown / delay X hours” control. All you can do is “turn off at a fixed time every day” — but my duration differs every day, so a fixed time is out right away.

iOS Shortcuts does have a “Wait” action, but a “Wait” in Shortcuts only runs on your phone, and it breaks once the screen has been locked for a while — relying on it for 2 hours is extremely unreliable.

Conclusion: a real countdown has to be handed to a machine that’s always awake. I happen to have a Raspberry Pi at home running Home Assistant (HA), which is the perfect candidate for this. So the question becomes: how does HA control this AC, and how do I hand control back to Apple Home.

The second bend (detective time): doesn’t the AC have its own timer?

This is the part I dug into the longest, and learned the most from.

My unit is a WAHIN (a Midea brand), connected in HA through the midea_ac_lan local LAN integration — meaning HA talks to the AC directly on the local network, not through the cloud. So, that “timer off” in the mini-program — is the cloud counting down for me, or is the AC counting down on its own?

At first I assumed “the cloud.” But then I thought, no: if the manufacturer ran a countdown in the cloud for tens of millions of ACs, the cost and logic make no sense. The countdown is almost certainly written into the AC unit itself and counted by its own firmware, and the mini-program just sends down the “turn off in N minutes” command.

If that’s the case, can I send that local command myself? I dug into the code of the midea-local library. The AC’s set command is the 0x40 packet in the protocol, and I went straight to reading the part where it builds the command body:

# midealocal/devices/ac/message.py · MessageGeneralSet._body
return bytearray([
    power | prompt_tone,
    mode | target_temperature,
    fan_speed,
    0x00,   # ← these hardcoded 0x00s...
    0x00,   # ← are exactly the on-timer / off-timer slots in the Midea protocol
    0x00,
    swing_mode,
    ...
])

The truth comes out: the protocol slots are right there (those 0x00s are exactly the timer bytes), but this local library never fills them in. Then I looked at the status response parsing (XC0MessageBody), which reads thirty-odd fields — temperature, mode, sleep, freeze protection… but never reads the timer. The only timer in the whole library is just a boolean “capability flag” in a sub-protocol, not a duration.

So the conclusion is clear:

My intuition was right — the AC firmware does support local timers, it’s not cloud logic;
But this open-source local integration never exposed that feature;
To use it, I’d have to hack the library (change command encoding, add writable entities), at the cost of being overwritten on every update, plus having to get the byte encoding right for your specific model;
And most critically: even if I wired it up, the HomeKit side still has no “duration control” available — the UI problem isn’t solved at all.

💡 A tip for fellow tinkerers: when you hit “this feature works in the app but isn’t in the integration,” go read the integration/library source first — you can often tell within ten minutes whether it’s “not exposed” or “not supported by the protocol.” This one step can save you several evenings of blind trial and error.

So I decisively backed off: don’t touch the library. Let HA do the countdown itself — a timer helper is stable enough, and even picks up again after a restart (restore: true). “Where the countdown runs” doesn’t actually affect the experience at all; what’s really unsolved is the next stage.

The third bend (crash site): HomeKit’s three walls

Requirement #5 is “operate it from Home while lying down.” I wanted a control like adjusting the AC temperature, one you can nudge +/- continuously, showing “how many hours” at a glance. Sounds easy, right? Apple taught me a lesson with three walls.

Wall one: HomeKit has no “number / duration slider.” I went through the HA HomeKit bridge source, and the control types it supports are just these: fans / lights / covers / humidifiers / thermostats / locks / switches / sensors… — no number. Your input_number simply can’t be passed through.

Wall two: there are only two units for continuous sliders. Going through it, only two categories render as “continuous slider/dial” in Apple’s native Home:

Control	Source	Display unit
Light brightness / fan speed / covers / humidifier	Percentage characteristic	locked to %
Thermostat	Temperature characteristic	locked to °

The unit is hardcoded by the protocol characteristic; Apple won’t let you change ° to “hours.” (Third-party HomeKit apps like Eve can show custom units, but with Apple’s native Home it’s just these two.)

Well… at least the thermostat’s number is real! If I set 2.5, it shows 2.5, just with a ° next to it — tolerable. So I actually built a fake thermostat with generic_thermostat, treating “temperature” as “hours,” declaring the range 0–8 with 0.5 steps.

Wall three, and the straw that broke this approach: Apple Home imposes a hard floor of ~7° on a thermostat’s target temperature. I had explicitly written min_temp: 0 in HA, but the dial on the phone can only be set to 7.0 / 7.5 / 8.0 — 0 through 7 all swallowed by Apple. I can’t exactly ask people to “set a minimum of 7 hours,” can I? This approach was scrapped on the spot.

🧱 One line to remember: in Apple’s native Home, if you want a fully continuous control, you either accept “the display is %” or accept “thermostat minimum 7°.” You can’t have both — real-number and full-range are mutually exclusive.

The final plan: finish with a “fan”

After hitting three walls, the way forward actually became clear: since “showing real hours” isn’t possible, take a step back and choose a percentage slider that never lags, and smooth over the “it’s a percentage” flaw with an easy-to-remember mapping.

I chose a fan (a light would also work; the fan wins because you can set the number of speed steps, which makes alignment easy):

Set speed_count: 20, so the slider has 20 steps, each step 5% = 0.5 hours, max 100% = 10 hours. Dragging snaps to the steps, so it’s easy to hit half-hour precision;
I made the mapping as easy to do in your head as possible: percentage ÷ 10 = hours. 30% → 3 hours, 25% → 2.5 hours;
This “fan” is really an empty shell. What actually stores the hours is the input_number behind it; the fan is just the wrapper it hands to HomeKit.

The full config is below, and HA users can copy it directly (I use packages to put a whole feature into one file, so it’s easy to roll back as a unit). You only need to replace the actual AC entity climate.197912093838856_climate with your own; everything else can be copied as-is.

# packages/skylight_ac_timer.yaml
# Bedroom AC · sleep timer off
#   In Apple Home, a "fan shell slider" fan.skylight_ac_timer:
#   percentage ÷ 10 = hours (30%→3h, 25%→2.5h), 20 steps, 0.5h each, max 10h, drag to 0 / off = cancel.
#   Behind it, input_number.skylight_ac_hours stores the hours; when the countdown ends, turn off the AC and reset to 0.
#   Fallback: check once at 23:00; if the AC is still on and no timer is set → start 3 hours (→ off at 02:00). AC on during the day doesn't enter this logic.

input_number:
  skylight_ac_hours:
    name: Bedroom AC timer hours
    min: 0
    max: 10
    step: 0.5
    mode: slider
    icon: mdi:timer-outline

timer:
  skylight_ac_manual:
    name: Bedroom AC manual countdown
    duration: "02:00:00"
    restore: true
  skylight_ac_fallback:
    name: Bedroom AC fallback countdown
    duration: "03:00:00"
    restore: true

# ⚠️ Uses the new template syntax (the old `fan: platform: template` will be removed in 2026.6)
template:
  - fan:
      - name: Bedroom AC timer
        default_entity_id: fan.skylight_ac_timer   # Lock the English entity_id; HomeKit bridge references are more stable
        state: "{{ 'on' if (states('input_number.skylight_ac_hours') | float(0) > 0) else 'off' }}"
        percentage: "{{ (states('input_number.skylight_ac_hours') | float(0) * 10) | int }}"
        speed_count: 20
        turn_on:
          - choose:
              - conditions:
                  - condition: template
                    value_template: "{{ states('input_number.skylight_ac_hours') | float(0) < 0.5 }}"
                sequence:
                  - action: input_number.set_value
                    target: { entity_id: input_number.skylight_ac_hours }
                    data: { value: 2 }   # Tapping "on" directly without dragging the slider = default 2 hours
                  - action: timer.start
                    target: { entity_id: timer.skylight_ac_manual }
                    data: { duration: "02:00:00" }
        turn_off:
          - action: input_number.set_value
            target: { entity_id: input_number.skylight_ac_hours }
            data: { value: 0 }
          - action: timer.cancel
            target: { entity_id: timer.skylight_ac_manual }
        set_percentage:
          - variables:
              hrs: "{{ ((percentage | float(0) / 10) * 2) | round(0) / 2 }}"  # Round to the nearest 0.5
          - action: input_number.set_value
            target: { entity_id: input_number.skylight_ac_hours }
            data: { value: "{{ hrs }}" }
          - choose:
              - conditions:
                  - condition: template
                    value_template: "{{ hrs >= 0.5 }}"
                sequence:
                  - action: timer.start
                    target: { entity_id: timer.skylight_ac_manual }
                    data:
                      duration: >
                        {% set s = (hrs * 3600) | int %}
                        {{ '%02d:%02d:00' % (s // 3600, (s % 3600) // 60) }}
            default:
              - action: timer.cancel
                target: { entity_id: timer.skylight_ac_manual }

automation:
  # Countdown ends: turn off AC + reset hours to 0
  - id: skylight_ac_manual_finish
    alias: Bedroom AC · countdown ends → turn off and reset
    trigger:
      - platform: event
        event_type: timer.finished
        event_data: { entity_id: timer.skylight_ac_manual }
    action:
      - service: climate.turn_off
        target: { entity_id: climate.197912093838856_climate }   # ← swap for your AC
      - service: input_number.set_value
        target: { entity_id: input_number.skylight_ac_hours }
        data: { value: 0 }

  # Fallback: fixed check at 23:00
  - id: skylight_ac_fallback_check_2300
    alias: Bedroom AC · 23:00 check → if on and no timer set, start 3-hour fallback
    trigger:
      - platform: time
        at: "23:00:00"
    condition:
      - condition: template
        value_template: >
          {{ states('climate.197912093838856_climate') not in ['off','unavailable','unknown'] }}
      - condition: state
        entity_id: timer.skylight_ac_manual
        state: idle
    action:
      - service: timer.start
        target: { entity_id: timer.skylight_ac_fallback }
        data: { duration: "03:00:00" }

  - id: skylight_ac_fallback_disarm
    alias: Bedroom AC · off → cancel fallback
    trigger:
      - platform: state
        entity_id: climate.197912093838856_climate
        to: "off"
    action:
      - service: timer.cancel
        target: { entity_id: timer.skylight_ac_fallback }

  - id: skylight_ac_fallback_finish
    alias: Bedroom AC · fallback 3 hours ends → turn off
    trigger:
      - platform: event
        event_type: timer.finished
        event_data: { entity_id: timer.skylight_ac_fallback }
    action:
      - service: climate.turn_off
        target: { entity_id: climate.197912093838856_climate }

A few design points worth calling out separately

Why not just have the fan store the hours directly instead of adding an input_number? Because a template fan is itself a “stateless” shell, and its percentage needs a real place to store it. The input_number is that “single source of truth”: the fan reads it for display and writes to it to make changes take effect, and the countdown resets it to zero when it finishes. That closes the loop, and you don’t have to worry about losing the value on a restart.

Why is the fallback “check once at 23:00” instead of “start a 3-hour timer whenever it turns on”? This is exactly the key to requirement #4 (don’t accidentally affect daytime use). If it were “arm a 3-hour fallback whenever it turns on,” then turning on the AC during the day would also be turned off automatically after 3 hours—not what we want. So I changed it to check only once at 23:00: only if the AC is still on then and no manual timer is set do we assume “this person fell asleep with the AC on” and give it a fallback shutdown. Daytime AC use never enters this logic at all.

(Small trade-off: if you don’t go into the bedroom and turn on the AC until after 23:00, the fallback won’t take effect that night—in that case just drag the slider manually. My schedule is regular and it basically fits, so I accepted this edge case.)

The manual timer takes priority over the fallback. The 23:00 check has the condition timer.skylight_ac_manual == idle: as long as you’ve already dragged the slider (the manual countdown is running), the fallback stays out of the way; they can also naturally overlap—if the manual timer is shorter, it turns off first, and the moment the AC turns off, it triggers “cancel fallback,” so it won’t fire twice.

How to get this control into Apple Home

HA has a built-in HomeKit Bridge integration that can expose specified entities as accessories in Apple Home. Just add the fan.skylight_ac_timer entity from above:

Settings → Devices & Services → find HomeKit Bridge → Configure → under “Entities to include” check fan.skylight_ac_timer → Save.

After a moment, a “Bedroom AC Timer” fan accessory shows up in Apple Home. Yes, the icon is a fan — that’s the price we pay for “a continuous slider all the way through.” Just think of it as a “countdown that blows the hot air away” 🌬️. Drag the slider, or tell Siri “set the bedroom AC timer to 30%,” and 3 hours later the AC puts itself to sleep.

One last small pitfall: old template syntax needs to be migrated

A few days after I finished, HA’s backend popped up a “Repair” notice: the old fan: platform: template syntax will be removed in 2026.6, and it asked me to migrate to the new template: → fan: syntax.

Fortunately, HA’s repair wizard generates the migrated config directly — just swap it in. The full config above is already in the new post-migration syntax, so if you copy it directly, you won’t see this reminder again. Here’s one more lesson while I’m at it:

🔧 Check HA’s “Repairs” panel regularly. Many deprecations are announced one or two versions ahead and come with an auto-generated new config — deal with them early; don’t wait until upgrade day for it to blow up in your face.

Quick-reference table of pitfalls

Here are the evening’s detours, condensed into one table, so you can find the one that applies to you:

Pitfall	The truth	The fix
Wanted to schedule directly in Home App	No native “delay/countdown” control	Let always-on HA handle the countdown (the `timer` helper)
Wanted to use the AC’s built-in timer	Firmware supports it, but the local integration doesn’t expose it (command byte hardcoded to 0)	Don’t hack the library; just let HA handle the countdown
Wanted a numeric slider	The HomeKit bridge has no `number` type	Borrow the percentage shell from a “fan/light”
Wanted the thermostat to show real hours	Apple Home pins the target temperature at a ~7° floor	Give up “real numbers” and use a % slider + an easy-to-remember mapping
Percentages aren’t intuitive	The unit can’t be changed	Pick a mapping that’s easy to do in your head, like `÷10` + `speed_count` to snap between steps
Old template syntax is deprecated	2026.6 removes `fan: platform: template`	Use the Repairs wizard to migrate to the new `template:`

Final thoughts

After a long detour, what I ended up with is very plain: lie in bed, drag the slider, and the AC quietly goes to sleep at the time I set; even if I fall asleep first, a 23:00 safety net catches it for me. An unassuming little tool, yet it genuinely erased the small chore of “getting up in the night to turn off the AC” from my life.

I really enjoy this kind of tinkering. On the surface it’s a fight with the AC; in essence, it’s dealing with those “invisible limits” — Apple’s floor, the zero hardcoded in the protocol, the old syntax about to be removed. Every wall you hit makes your understanding of the system a little deeper. And the most interesting part is often not the final config you can copy, but the whole evening behind “why a fan, of all things.”

May you also install one or two such “sleepy” little switches into your own life.

—— Add a little sunshine to your life ☀️

Making the Loctek E2 Standing Desk Smart: ESP32 + ESPHome + Home Assistant

Sun, 31 May 2026 00:00:00 +0000

I recently connected the Loctek E2 standing desk at home to Home Assistant, and then exposed it to Apple Home. The end result: tap “sit” or “stand” in the Home app, and the desk automatically moves to the sitting or standing memory height.

At first this looked like a simple little task: find two wires and briefly short them together. It was only after actually tinkering with it that I realized that the hand controller port on desks like Loctek’s isn’t a traditional button-shorting setup, but a UART serial protocol running over the RJ45 cable.

This post documents the whole process: how to identify the pins, how to confirm the protocol, how to connect it to Home Assistant with ESP32 + ESPHome, and finally how to handle power and HomeKit control.

Final result

On the hardware side, I kept the desk’s original hand controller panel; the ESP32 is just connected in parallel to the serial lines in the hand controller port.

On the software side, the chain now looks like this:

Apple Home / Siri
        ↓
Home Assistant
        ↓
ESPHome API
        ↓
ESP32 UART
        ↓
Loctek E2 standing desk controller

What it can do now:

Two buttons in Home Assistant: sit and stand
I can also trigger these two actions in Apple Home
The ESP32 doesn’t need a separate USB power supply; it’s powered directly by the 5V on the desk’s RJ45 port
The desk’s original hand controller is unaffected, and the physical buttons still work normally

Hardware list

I used quite a few things this time, and it was my first time working with a microcontroller:

Loctek E2 standing desk
ESP32-WROOM-32 dev board, 30Pin, Type-C port
RJ45 to 8Pin solderless terminal block
A few jumper wires
Multimeter
A Raspberry Pi running the Docker version of Home Assistant

Since I can’t solder, I tried to make the whole approach “solderless, detachable, and reversible” as much as possible. All connections are jumper wires plus screw terminals.

Phase 1: Confirming it’s not ordinary buttons

My first thought was: the standing desk hand controller has up, down, and 1, 2, 3, 4 memory positions, so maybe the RJ45 just contains a few button wires, and pressing a button just grounds one of the wires.

That turned out not to be the case.

After debugging the UART on the ESP32, I found that the desk continuously broadcasts data even when stationary. After testing baud rates, 9600 was the most stable.

When the desk is stationary, I see frames like this:

9B:04:11:7C:C3:9D
9B:07:12:00:00:00:B8:94:9D

When the desk moves, the data changes noticeably, for example:

7F:FD:06:F2:65:9D
7F:87:3F:80:86:9D
06:06:7F:F9:36:9D

This was a key step. It showed that the hand controller port isn’t a simple button-shorting setup, but UART serial communication.

Measuring the RJ45 pins

Hold the RJ45 connector like this:

Metal contacts facing up
Clip facing down
Cable pointing away from you

What I measured:

pin1: about 5.11V
pin2: GND
pin3: about 4.1V
pin4: about 4.2V
Other pins about 0V

Later testing confirmed:

pin1 can power the ESP32’s VIN
pin2 is GND
pin3 / pin4 are UART TX/RX

There’s one risk here: strictly speaking, the ESP32’s GPIO is not 5V tolerant, and the UART lines here measure over 4V. It works in my actual testing, but a more rigorous long-term solution should add level shifting or a voltage divider between the desk’s TX and the ESP32’s RX. For now I’m going with the minimal change.

ESP32 wiring

On the ESP32 side, I used:

GPIO16 / D16
GPIO17 / D17
GND
VIN

Final wiring:

RJ45 pin1  +5V   -> ESP32 VIN
RJ45 pin2  GND   -> ESP32 GND
RJ45 TX          -> ESP32 RX / GPIO16
RJ45 RX          -> ESP32 TX / GPIO17

Note: the ESP32’s TX goes to the desk’s RX, and the ESP32’s RX goes to the desk’s TX. If you don’t get data, swap TX/RX first.

Also, the desk’s 5V goes to the ESP32’s VIN, not 3V3. VIN is the 5V input, which goes through the onboard regulator to become the 3.3V the ESP32 uses; 3V3 is the already-regulated 3.3V power pin on the board, and connecting 5V to it will likely burn the board.

When testing the desk’s 5V supply, I first unplugged the USB from the computer and used only the desk’s pin1 -> VIN and pin2 -> GND to power the ESP32. After confirming it came online reliably, I reconnected TX/RX and tested sit and stand.

ESPHome configuration

The final ESPHome configuration is very short:

esphome:
  name: desk

esp32:
  board: esp32dev
  framework:
    type: arduino

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

logger:
  baud_rate: 0

api:

ota:
  platform: esphome

uart:
  id: desk_uart
  baud_rate: 9600
  tx_pin: GPIO17
  rx_pin: GPIO16

button:
  - platform: template
    name: "sit"
    id: sit
    on_press:
      - uart.write:
          id: desk_uart
          data: [0x9b, 0x06, 0x02, 0x04, 0x00, 0xac, 0xa3, 0x9d]

  - platform: template
    name: "stand"
    id: stand
    on_press:
      - uart.write:
          id: desk_uart
          data: [0x9b, 0x06, 0x02, 0x08, 0x00, 0xac, 0xa6, 0x9d]

At first I used switch here, then later changed it to button. The reason is simple: sitting and standing aren’t “switch states” but one-shot commands. If I used a switch, Home Assistant would mistakenly think it has a persistent on/off state; but in reality, pressing stand doesn’t mean the desk has definitely arrived, nor can it know whether it was interrupted midway by the hand controller.

So for now, the most accurate model is:

sit: send the sitting memory-position command once
stand: send the standing memory-position command once

Later, once I can decode the height frames, I’ll consider upgrading to sensor + number + select, or even making it a cover model similar to curtains.

Reading the current state

Later I did another round of tests reading the state. The goal wasn’t to keep reverse-engineering the whole protocol in depth, but to solve a practical problem first: Home Assistant should at least know whether the desk is roughly sitting, standing, or moving.

When the desk is stationary, it continuously sends frames like this:

9B:04:11:7C:C3:9D
9B:07:12:00:00:00:B8:94:9D

But these two idle frames alone can’t distinguish sitting from standing. In other words, if the ESP32 has just cold-started and the desk hasn’t moved, these two idle frames alone can’t tell what height the desk is at.

What’s really useful are the frames during sit-stand transitions. From my testing, I can currently use the following signals to tell:

9B:04:15:BF:C2:9D              # desk is moving
9B:07:12:07:CF:...:...:9D      # sitting preset related state
9B:07:12:06:06:...:...:9D      # standing preset related state

So ESPHome now has a few more state entities:

text_sensor.desk_posture       # sitting / standing / unknown
binary_sensor.desk_sitting
binary_sensor.desk_standing
binary_sensor.desk_moving

I didn’t make sitting and standing into a switch here. The reason is it’s not a real switch: the physical panel can also change the desk state, and it can be interrupted midway. A more accurate design is to keep the two sit / stand buttons and expose read-only state separately.

Here are the actual test results:

stand -> sit:
initially standing
after pressing sit, moving=true
about 21 seconds later, moving=false
finally sitting=true, standing=false, posture=sitting

sit -> stand:
initially sitting
after pressing stand, moving=true
about 21 seconds later, moving=false
finally sitting=false, standing=true, posture=standing

In addition, I also tested pressing the desk’s physical panel 1 key directly. After the desk returned to sitting, Home Assistant also read it in sync:

sitting=true
standing=false
moving=false
posture=sitting

This shows that the ESP32 isn’t just aware of the commands it sent itself; it’s actually listening in on the desk’s UART communication. Whether the action is triggered by Home Assistant or by pressing the physical panel, as long as the desk completes a sit-stand transition, the state gets updated.

The current limitation is also clear: the first stationary state after a cold start may only restore the last recorded state, and doesn’t necessarily reflect the real height. But as long as one sit-stand action happens afterward, the state becomes reliable again. For my current use, that’s enough.

Home Assistant integration

Home Assistant is a newly installed Docker version on the Raspberry Pi, at an address like:

http://192.168.31.123:8123

After flashing the ESPHome node, Home Assistant automatically discovered desk. After adding the ESPHome integration, I could see two entities:

button.desk_sit
button.desk_stand

I also set up a DHCP static binding for the ESP32 in the router, so the IP won’t drift after each power loss and reconnect, and the Home Assistant connection is more stable.

Connecting to Apple Home

To expose entities in Home Assistant to Apple Home, I used Home Assistant’s HomeKit Bridge.

Path:

Settings -> Devices & services -> Add Integration -> HomeKit Bridge

When creating the HomeKit Bridge, select only the desk-related entities to expose:

button.desk_sit
button.desk_stand

Home Assistant then gives you a HomeKit pairing QR code or PIN. Open the Home app on your iPhone, add an accessory, and scan the code or enter the PIN.

If you’re running Home Assistant in Docker and HomeKit can’t find the Bridge, it’s usually related to network mode and mDNS broadcast. The simplest fix is to let the Home Assistant container use host network, so it shares the same broadcast domain as your LAN devices.

Power: from computer USB to the desk’s 5V

At first the ESP32 was powered from the computer’s USB-C port, with only these wires connected:

RJ45 GND -> ESP32 GND
RJ45 TX/RX -> ESP32 RX/TX

This is “listen-only mode”. It’s safer, but not suitable for long-term use: I’d still have to hang a USB power cable under the desk, which is very inelegant.

Later, after confirming RJ45 pin1 was about 5.11V, I connected it to the ESP32’s VIN. It was stable in testing, and no external USB power was needed.

A few notes:

Connect 5V to VIN, not 3V3
Connect GND to a real GND
Don’t have computer USB and the desk’s 5V connected at the same time while testing
Measure pin1 to pin2 with the multimeter’s voltage mode, not by shorting with current mode

I also made a small mistake: I once connected GND to the adjacent D13. Fortunately the current firmware doesn’t use D13, so it didn’t actually cause any problems. But this mistake reminded me that I must secure the wiring when I finish, and not leave Dupont wires under stress or wobbling for long periods.

What’s still not perfect

Functionally it works, but it still looks like an engineering prototype: a thick RJ45 cable, a few Dupont wires, and a bare ESP32 board hanging under the desk.

Next I plan to make a small box to house the RJ45 terminal and the ESP32:

Use a small ABS project box
Switch to a short, soft, flat RJ45 cable
Secure the ESP32 and terminal with double-sided tape or mounting bases
Add strain relief at the cable entry, so pulling from outside doesn’t act directly on the screw terminals
Attach the whole box to the underside of the desk with Velcro

The goal is to end up with only a small box and a short cable visible, not a tangle of experimental wiring.

What I got out of this tinkering

The biggest takeaway wasn’t “making the desk controllable from a phone”, but methodically breaking a closed, ordinary piece of furniture into several understandable problems:

Is its interface for power and buttons?
If it isn’t buttons, what protocol is it speaking?
How can I just listen, without risking interference with the original controller?
How do I send the minimal command to switch to sit/stand?
How do I make Home Assistant and Apple Home see it as a normal smart home device?
How do I replace the temporary USB power with power from inside the desk?

The final answer is quite simple:

Loctek E2 RJ45 hand controller interface
  -> UART 9600
  -> ESP32 + ESPHome
  -> Home Assistant
  -> HomeKit Bridge
  -> Apple Home

Now this desk is finally not just an “electric standing desk”, but part of my smart home system.

Next step: turning the desk into a real health reminder

The desk can now be controlled by Home Assistant and Apple Home, but it’s still essentially “manually triggered”: I tap a button when I want to sit or stand.

Next I want to turn it into a more proactive health workflow: combining sensors and a Pomodoro timer, so the desk automatically reminds me at the right time, or even forces a switch between sitting and standing.

Initial ideas:

Use a presence sensor, a chair pressure sensor, or computer activity to determine whether I’m actually at the desk
Use Home Assistant to implement Pomodoro logic: automatically switch to stand after 25 minutes of work
After standing for 5 minutes, allow switching back to sit
If the sensor says I’m not at the desk, don’t trigger the desk movement, so an empty desk doesn’t move on its own
Later, if I can parse the desk’s height data, I’ll add a check so it doesn’t repeat if it’s already standing

The key point of this version is no longer “can I control the desk”, but “when should I control it”. The truly useful part of a smart home is often not turning your phone into a remote control, but letting devices do the right thing on their own according to the situation.

Hands-on sequel: I actually built the pomodoro timer

That was the idea. Later I built the whole thing. The end result:

When I’ve worked at the desk for a full 30 minutes, the desk automatically switches between sitting and standing (the rule is “change posture every 30 minutes”; the first 5 minutes after a switch are a “mental break”)
When I leave the desk, the pomodoro pauses automatically; the desk won’t go up and down on its own in front of an empty chair
If I’m away more than 10 minutes (lunch, say) and come back, it automatically starts a new round, returns to the sitting position, and restarts the timer
When I record vocals, open LogicPro, or am in a meeting, I switch to a macOS Focus mode and the whole desk freezes
Hard freeze from 23:00 to 07:00 the next morning; it won’t move for any reason, so I’m not startled by movement in the middle of the night
No GUI app running on the Mac at all; everything runs in the background

After all the work on this version, the time really went into platform and environment pitfalls, not into “writing the automation”. Below I’ve written down the architecture, the decision logic and the three hard pitfalls.

How to tell whether I’m at the desk

This is the input signal for the whole setup. I compared a few approaches:

ping / online probe: only tells you “powered on and online”, can’t distinguish “in use” from “lid closed and asleep”. No good.
HA Companion App: install the official macOS app and it reports Active status; the least effort. But it’s a resident GUI program, and by default it reports a pile of stuff (foreground app, camera, location…). I wanted it unobtrusive. No good.
Final approach: read macOS’s built-in HIDIdleTime (nanoseconds since the last keyboard/mouse input), and have a background script report it to HA on a schedule. This is the only signal that truly reflects whether the keyboard or mouse is being used.

ioreg -c IOHIDSystem | awk '/HIDIdleTime/ {print int($NF/1000000000)}'

Overall architecture and data flow

The final chain looks like this (I’ll explain later why it detours through a webhook in the middle):

Mac launchd（每 20 秒）
  └─ /usr/bin/curl ──HTTP──▶ HA Webhook（接收 idle 秒数）
                                └─ 自动化 mqtt.publish ─▶ mosquitto（topic: mac/desk/idle）
                                      └─ MQTT sensor（expire_after 90s）
                                            └─ binary_sensor.mac_at_desk（idle < 180s）
                                                  └─ should_run（在桌前 且 未专注 且 非夜间）
                                                        └─ timer（30 分钟）
                                                              └─ 到点 ─▶ button.desk_sit / desk_stand

mosquitto runs in Docker on a Raspberry Pi, with anonymous access off and username/password plus ACL on. HA connects to it with the ha account.

Decision logic: splitting “should it move” into independently verifiable booleans

I didn’t lump all the logic together. I split it into a few intermediate values whose truth you can test at a glance:

1. Am I at the desk

# binary_sensor.mac_at_desk
state: >
  {% set v = states('sensor.mac_idle_seconds') %}
  {{ v not in ['unknown','unavailable','none', None] and (v | int(99999) < 180) }}

Note the MQTT sensor has expire_after: 90: once the Mac sleeps or the lid closes, launchd stops reporting, and if no data arrives within 90 seconds the sensor goes inactive → at_desk turns off → the desk by default doesn’t move. That’s a “disconnected means safe” fallback.

2. Should the pomodoro be running (three gates combined)

# binary_sensor.desk_pomodoro_should_run
state: >
  {% set t = now() %}
  {% set night = t.hour >= 23 or t.hour < 7 %}
  {{ is_state('binary_sensor.mac_at_desk','on')
     and is_state('input_boolean.desk_pause_focus','off')
     and not night }}

The timer only runs when should_run is on; if any of away-from-desk / focus / night holds, it immediately does timer.pause.

3. When I come back, do I “resume” or “start a new round” (there’s a pitfall here I only found later)

This is the most critical part of the experience. A short absence (bathroom, getting water) should pick up where it left off; a long absence (lunch) should start over. I use “length of absence” to tell them apart:

# 触发器：HA 启动 + should_run 任意 → on（关键：别只写 from: "off"）
# 条件：should_run 为 on，且 timer 当前不是 active（避免重复启动）
away_secs: >
  {% if trigger.platform == 'state' and trigger.from_state
        and trigger.from_state.state == 'off' and trigger.to_state %}
    {{ (trigger.to_state.last_changed - trigger.from_state.last_changed).total_seconds() }}
  {% else %}
    99999
  {% endif %}
# away_secs < 600 且 timer 处于 paused → timer.start（续上）
# 否则 → 起 30 分钟（开新一轮，从当前姿势开始，不强制移动桌子）

This one rule covers lunch, the end of the night period, the end of a long recording session and every other “away for a long time” case, without writing each one separately.

⚠️ Don’t do what I did at first: my first trigger only had from: "off" → to: "on", which planted a landmine. Every time Home Assistant restarted, should_run went from unknown → on, which doesn’t match off→on, so the startup automation never fired — the pomodoro just sat at idle and the desk never moved again; and since the whole thing had no “start on boot” fallback, it meant one restart and it was dead (I restarted a dozen times in a row while cleaning up the config before I noticed it had long stopped working).

The fix: widen the trigger to “any → on” and add “HA start (platform: homeassistant, event: start)”, then use the “timer is not active” condition to catch duplicate starts; away_secs is only computed on a real off→on, everything else (boot, unknown→on) is treated as a new round. “Only recognising one particular state transition” is one of the most common pitfalls in HA automations — always include the unknown from a restart / cold start.

4. Switching posture when time’s up

# timer.finished 时
# 当前是坐姿 → 按 stand；否则 → 按 sit

One small improvement I added later: the timer is really “how long the current posture has been held”. So it’s not only the automatic flip at time-up that resets it — if you manually switch posture yourself, the 30 minutes also restart from the moment it settles, so you don’t get the awkward “stood up a few minutes ago and it flipped me back to sitting”. Implementation-wise, it just listens for the desk settling into either sitting or standing while should_run is on, and does timer.start for 30 minutes.

Because should_run is always off at night and the timer is paused, finished never fires, so the 23:00–07:00 hard freeze holds naturally without any extra interception.

5. How to pause for recording / meetings

I didn’t go identify “is LogicPro in the foreground”, “is the camera in use” and other numerous, fragile conditions one by one. Instead I use a macOS Focus mode as the master switch: build two personal automations with Shortcuts (a macOS automation app), each doing a curl to an HA webhook when the Focus mode turns on / off, and HA flips input_boolean.desk_pause_focus. Single source of truth, clean.

Three pitfalls that stopped me (the most valuable part this time)

Pitfall one: macOS 26’s “Local Network privacy” is granted per binary

At first I had the Mac-side script use mosquitto_pub to send data straight to the broker on the Raspberry Pi. Running it by hand in the terminal — success; handed to launchd to run in the background — runs was going up, exit code 0, but the broker received nothing.

Switching to a direct Python connection made the error clearer: [Errno 65] No route to host. But in the same launchd context, curl to the Raspberry Pi returned 200.

Conclusion: macOS 26’s Local Network privacy is granted per executable. Running by hand in the terminal, the process inherits the terminal app’s “Local Network” permission; a headless process launched by launchd is a separate identity without that permission, so Homebrew’s python3 / mosquitto_pub get silently denied access to the LAN. /usr/bin/curl is an Apple-signed system binary and gets through.

The key diagnostic step was trying curl and a direct MQTT connection in the same launchd script:

launchd 上下文：curl_to_pi=200      ← 网络是通的
launchd 上下文：mosquitto/python 失败 ← 只有三方二进制被拦

The fix: let the permitted curl make the hop across the LAN. The Mac no longer connects to the broker directly; it curls an HA webhook, and HA then does mqtt.publish internally. That gets around Local Network privacy while keeping the broker, the least-privilege account and the expire_after safety net.

Pitfall two: mosquitto_pub reports “Bad file descriptor” under launchd

It’s really the poor-quality error message from pitfall one — after the socket is denied by Local Network privacy, mosquitto’s network loop hits a bad fd and reports Error: Bad file descriptor, which sends you off in the stdin/fd direction. Only switching to Python and seeing No route to host made the truth clear.

Pitfall three: a Chinese name generates a pinyin entity_id, and all cross-entity references break

In HA, the entity_id of MQTT / template entities is generated by slugifying the name. To save effort I gave a sensor the Chinese name Mac 空闲秒数, and HA turned it into pinyin:

sensor.mac_kong_xian_miao_shu
binary_sensor.mac_zai_zhuo_qian

But my templates referenced the English sensor.mac_idle_seconds — so it never got a value, and at_desk was always off. The symptom was confusing: the data was clearly updating on the dashboard, yet the sensor stayed off.

(input_boolean / timer aren’t affected; their entity_id comes from the key name in the config, not from name.)

Lesson: for any technical entity that other templates / automations will reference, always use an English name so the entity_id is clean and predictable; leaving it in Chinese is unsafe because it ends up in the id.

There’s also a small related pitfall: in ioreg | awk '… exit}', awk stops on the first match, which sends SIGPIPE to the upstream ioreg, and combined with the script’s set -e -o pipefail it makes the script “quietly exit early” after getting the idle value, never reaching the reporting step. Just remove awk’s early exit.

A little takeaway

I came away with two main lessons.

First, split complex decisions into a chain of booleans you can feed values into and verify independently: at desk / not focused / not night, each layer can be tested on its own by curling a value in and reading the true value back from the database, so when debugging you’re not facing a black box.

Second, the devil in cross-platform automation is in the environment details, not the main logic: Local Network privacy granted per binary, the Chinese-to-pinyin slug rule — these things are perfectly valid in config syntax, yet they silently break the whole chain. Clearly verifying whether each hop actually gets through is far faster than rereading the YAML over and over.

Ukulele Mixing in Logic Pro: From Thin to Record-Ready

Wed, 06 May 2026 00:00:00 +0000

Ukulele Mixing in Logic Pro: From “Thin and Dry” to “Record-Ready” Sound

Because the ukulele has a small resonating body, recordings often sound thin and dry. How do you dial in a tone that’s both full and solid, yet bright and clear?

This article breaks down two approaches: one uses Logic Pro’s built-in plugins to get fast results; the other uses the UADx series of top-tier analog-modeling plugins to create that ultra-high-end feel.

🎧 Core Mixing Approach

Cut the mud → Add fullness (compression) → Add air (EQ) → Create space (reverb)

Part 1: A Must-Have for Beginners! All Built-In Plugins

If you’re a beginner, Logic Pro’s built-in plugins are more than enough. The key is in the parameter details.

1. Basic Cleanup (Channel EQ)

High Pass: Enable the left-side filter and cut everything below 100Hz. Remove hum and unwanted rumble.
Notch: Apply a slight -3dB cut around 300Hz-500Hz to fix the dull, “hiding in a cardboard box” feel.

2. Add Thickness (Compressor)

Model: Choose [Vintage Opto] (silver panel).
Key settings: Set Attack to 20ms-40ms to preserve the crisp “ding” of the plucked strings. Lower Threshold until the needle swings to -3dB.
Effect: The sound instantly becomes smoother and more solid, no longer thin.

3. Brighten the Tone (Vintage Tube EQ & Exciter)

Vintage Tube EQ: Set the frequency to 10kHz and turn the Boost knob to 3-5. This gives the tone a “sequined outfit.”
Exciter: Gently add 10% Harmonics. It generates natural high-frequency overtones that make the sound more penetrating.

4. Wrapping It in Space (ChromaVerb)

Must-do: Set up a Bus send and put the reverb on an auxiliary track.
Settings: Choose the Room type. Set Pre-Delay to 20ms (key! Let the dry signal come through first so the sound stays clear).

Part 2: A Leap in Quality! The Top-Tier UADx Plugins Version

If you’re after the warmth of analog gear and more refined highs, this “golden chain” is your first choice.

1. Fullness That Adds Soul (UADx LA-2A Tube Compressor)

The LA-2A is the most famous optical compressor in history, and it’s a “perfect match” for the ukulele.

How to use: Turn the Peak Reduction knob until the large meter needle swings to -2 or -3 on the heaviest strums.
What you hear: It’s not just controlling volume; it adds the warmth and thickness of tubes, giving the tone more body.

2. Heavenly Brightness and Air (UADx Pultec EQP-1A)

This is the pinnacle of the EQ world, and its high-frequency boost is incredibly silky.

How to use: Set High Frequency on the right to 10kc or 12kc. Slowly raise Boost.
What you hear: The ukulele’s highs take on an “airy” quality—sweet and clear without being harsh—a texture that digital EQs struggle to achieve.

3. Enhance Midrange Penetration (UADx Pultec MEQ-5)

Settings: In the Peak section, choose 1.5k or 2k and boost slightly by 1-2dB.
Effect: This step makes the instrument’s fundamental clearer, letting the sound instantly “jump out” of the backing track.

4. Intelligent Space Processing (sonible smartReverb)

How to use: Let smartReverb learn your material. It automatically avoids muddy frequencies and generates the most fitting reverb.
Advanced: Pair it with the Haas effect (a Stereo Delay with a 20ms difference between the left and right channels) to instantly make a single ukulele track as wide as a stereo recording.

✅ Summary: Post-Mix Checklist

Did you high-pass? (100Hz, to fix muddiness)
Is it solid? (Use a compressor to make the sound full)
Is it bright? (Use a vintage EQ to boost highs around 10kHz)
Is it muddy? (Did you set Pre-Delay on the reverb, and did you cut the reverb’s low end?)

Following this logic, whether you’re singing while playing or playing instrumentally, your ukulele track will take on a professional, radio-ready quality!

#LogicPro #Ukulele #MixingTutorial #UADPlugins #MusicProduction #IndependentMusician

SUNO and Logic Pro Assisted Arrangement: Platform Approval and Mixing SOP

Wed, 08 Apr 2026 00:00:00 +0000

Disclaimer: The following is for music production hobbyists’ reference only. It summarizes my personal experience: assuming I already have original lyrics and composition and sing the vocals myself, I use SUNO and Logic Pro for arrangement assistance and adjust my mixing workflow so I don’t lose the copyright in my lyrics and composition because of the default AI song. Do not use this method for anything illegal or that infringes copyright.

Core logic: Use “physical analog coloration” to mask the digital characteristics of AI audio (checkerboard noise, high-frequency cliffs, invisible watermarks), and also keep the “AI backing track” and “real human recordings” physically separate at the bus level, creating the acoustic illusion of a “real studio-made backing track + real vocals”.

📍 Stage 1: Material cleanup (clearing landmines)

Goal: Remove the “problem areas” most likely to trigger AI detection.

Import the stems: Import the individual instrument stems generated by Suno or another AI tool into Logic Pro.
Delete the AI vocals outright (fatal landmine): AI-generated lead and backing vocals sound strongly metallic and synthetic, with phase defects. They must be fully deleted, muted, or discarded outright, and replaced entirely with vocals and harmonies you recorded yourself.
(Optional, advanced) Drum doubling: If the AI drums sound too digital, select the drum track and use Track -> Drum Replacement/Doubling to layer on a real drum machine sample built into Logic.

📍 Stage 2: Group isolation (core architecture)

Goal: Prevent AI backing-track processing from “collaterally damaging” the clean human vocals.

Select all AI-generated instrument tracks (woodwinds, strings, synths, guitar, bass, drums, etc.).
Press Command + Shift + D.
Choose Summing Stack and click Create.
Rename the new main track to “AI Backing Bus”.
Note: All vocals and live instruments you recorded yourself must stay outside this bus and go directly to Stereo Out.

📍 Stage 3: Physical analog coloration (breaking the AI watermark)

Goal: Add analog-circuit harmonics to the backing bus to break up the regularity of the AI spectrum.

In the Audio FX chain of the “AI Backing Bus”, insert Phat FX and set the parameters as follows:

BANDPASS: Completely off (greyed out).
DISTORTION: On.
- Bit Crush: 0.0%
- Sat: 10% - 15%
- Vari Drive: choose Tube or Soft, push to around 5%.
BASS ENHANCER: On.
- Type: Warm
- Amount: 10% - 15% (disrupts the low-frequency phase)
COMPRESSOR: On.
- Type: Vintage VCA (adds hardware nonlinearity)
- Amount: 15% - 20%
MASTER (main output mix) - the most critical:
- Turn the Mix knob to 25% - 30%.
- (Note: use just 30% analog coloration to dirty up the background while keeping 70% of the original clarity.)

📍 Stage 4: High-frequency cliff repair (fooling the spectrum analyzer)

Goal: Fix the cliff where the AI backing track is cut off above 18kHz.

On the “AI Backing Bus”, right after Phat FX, insert a Channel EQ:

Turn on the High Cut / Low Pass filter on the far right.
Set the cutoff frequency to around 17500 Hz.
Set the slope to the gentlest setting, 12dB/Oct.
- (Note: artificially recreate the natural high-frequency rolloff of old gear to mask the unnatural drop-off caused by insufficient AI compute.)

📍 Stage 5: Mixing and export

Vocal blending: On the Stereo Out bus, insert your usual mastering chain (a bit of bus glue compression, a limiter, etc.) so the clean human vocals blend naturally with the backing track’s “physical patina”.
No need to change BPM: Once you apply the bus coloration above, the AI’s acoustic fingerprint is completely covered. There’s no need to force a slight BPM adjustment across the whole song (to avoid severe track misalignment when Flex is not enabled).
Export format: Bounce it as usual to a 24-bit / 48kHz WAV file.

💡 Notes and summary

For audio exported with this workflow, the detection algorithm will read it as: “extremely realistic vocals + a backing track with the studio character of analog hardware”, so it’s judged to be traditional human music production and passes AI detection.

Building an Always-Online AI Assistant: A Complete Guide to Deploying the PicoClaw Feishu Bot on Raspberry Pi

Mon, 09 Mar 2026 00:00:00 +0000

In this tutorial, we’ll use a Raspberry Pi as a local server, deploy the PicoClaw gateway, and seamlessly connect Feishu to powerful cloud LLMs (such as Volcengine) to build a dedicated, enterprise-grade AI assistant that responds to your commands anytime, anywhere.

1. Hardware Preparation

Choosing the right hardware is the first step toward success, and it saves you from 90% of low-level errors.

Raspberry Pi host: I strongly recommend a Raspberry Pi 3B / 3B+ / 4B / 5 or Zero 2 W.

❌ Watch out: Absolutely do not use the first-generation Raspberry Pi Zero W (v1.1) or Pi 1/2! Modern high-performance gateways (including Feishu’s long-connection SDK) require a 64-bit (ARMv8 / aarch64) architecture. The old Zero W’s chip is 32-bit, so forcing it to run just throws an architecture-not-supported error.
Other peripherals: A 16GB or larger MicroSD card and a stable power supply (5V 2.5A or above).
How to operate: Although this tutorial can be done headless over SSH, if you can, I strongly recommend plugging in a monitor and keyboard directly, so you can actually see the boot screen and the IP address — troubleshooting is much easier that way.

2. Software and Environment Choices

Operating system: We’re using the Raspberry Pi OS (64-bit) desktop version, flashed with Raspberry Pi Imager v2.0.6 (A port of Debian Trixie with the Raspberry Pi Desktop), released 2025-12-04. The desktop version has more features and is friendlier to beginners. Make sure it’s the 64-bit one.
File manager (FileZilla): I strongly recommend downloading and installing FileZilla on your computer. It’s a free FTP tool that lets you connect directly to the Raspberry Pi over SFTP. With it you can double-click to open, edit and sync config files — far nicer than typing tedious commands into the terminal.

3. Core Deployment Process

3.1 Flashing the System and Booting

After flashing the system with Raspberry Pi Imager, insert the SD card into the Raspberry Pi and boot it. Connect to your home Wi-Fi and note down the Raspberry Pi’s IP address (e.g. 192.168.31.101).

3.2 Final Architecture Check

Run this command in the Raspberry Pi terminal (or over SSH from your computer). If the output is aarch64, congratulations — your hardware is ready to go!

Bash

uname -m

3.3 Downloading, Installing and Initializing PicoClaw

Since we’re on a 64-bit system, just download the aarch64 version of the .deb package and run the following in order:

Bash

# 1. Download the package (check Github's latest release for the version number)
wget https://github.com/sipeed/picoclaw/releases/download/v0.2.1/picoclaw_aarch64.deb

# 2. Install the package
sudo dpkg -i picoclaw_aarch64.deb

# 3. Initialize the working directory (generates default config)
picoclaw onboard

Once the init command finishes, the terminal prints the cute lobster icon and the guidance below, telling you the config folder has been created:

Plaintext

pi@raspberrypi:~ $ picoclaw onboard
🦞 picoclaw is ready!

Next steps:
  1. Add your API key to /home/pi/.picoclaw/config.json

Recommended:
  - OpenRouter: https://openrouter.ai/keys (access 100+ models)
  - Ollama:     https://ollama.com (local, free)

  See README.md for 17+ supported providers.

  2. Chat: picoclaw agent -m "Hello!"

4. The Ultimate Config File Walkthrough (Copy-Paste Zone)

After initialization, open FileZilla, connect to the Raspberry Pi, find /home/pi/.picoclaw/config.json, and right-click to edit it.

You can copy the configuration below — which I’ve verified runs perfectly — straight in and overwrite the original contents (remember to replace the places with XXXX).

(Note: standard JSON doesn’t support // comments, but I kept them to make things easier to understand. If you get an error when running it, delete the comments manually):

JSON

{
  "session": {
    "dm_scope": "per-channel-peer"
  },
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "restrict_to_workspace": true,
      "provider": "openai",
      "model": "volcengine",
      "max_tokens": 32768,
      "max_tool_iterations": 50
    }
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "app_id": "cli_XXXXXXXXXXXXXXXXX", // Feishu app_id
      "app_secret": "XXXXXXXXXXXXXXXXX", // Feishu app_secret
      "encrypt_key": "picoclaw",
      "verification_token": "uEWQaEyh48hQdKXXXXXXXXXXXXXXXX", // Feishu verification_token
      "allow_from": [],
      "group_trigger": {},
      "reasoning_channel_id": ""
    },
    "maixcam": { "enabled": false, "host": "0.0.0.0", "port": 18790 },
    "qq": { "enabled": false },
    "dingtalk": { "enabled": false },
    "wecom": { "enabled": false },
    "wecom_app": { "enabled": false },
    "pico": { "enabled": false }
  },
  "model_list": [
    {
      "model_name": "volcengine",
      "model": "openai/kimi-k2.5", // Pick a model name from your LLM model list
      "api_base": "https://ark.cn-beijing.volces.com/api/coding/v3", // This is Volcengine's API address
      "api_key": "11XXXX72-XXXX-XXXX-XXXX-XXXXXXXXX" // This is Volcengine's API key
    }
  ],
  "gateway": {
    "host": "127.0.0.1",
    "port": 18790
  },
  "tools": {
    "web": {
      "duckduckgo": { "enabled": true, "max_results": 5 }
    },
    "cron": { "exec_timeout_minutes": 5 },
    "exec": { "enable_deny_patterns": true },
    "skills": {
      "registries": {
        "clawhub": { "enabled": true, "base_url": "https://clawhub.ai" }
      },
      "max_concurrent_searches": 2
    },
    "media_cleanup": {
      "enabled": true,
      "max_age_minutes": 30,
      "interval_minutes": 5
    }
  },
  "heartbeat": {
    "enabled": true,
    "interval": 30
  }
}

🔑 Where to Find the Keys

Feishu credentials (app_id, app_secret, verification_token): Go to the Feishu Developer Console -> your app -> the “Credentials & Basic Info” and “Events & Callbacks” pages in the left menu.
LLM credentials (api_key): Go to the Volcengine AI Console -> “API Key Management”.

5. Feishu developer console permissions and event configuration (⚠️ very easy to get wrong)

This is the key step that determines whether your bot can “speak”. Countless people get stuck here and end up with “read but no reply”. Be sure to follow these steps in order:

Step 1: Give the “bot” a soul (extremely easy to miss!)

After creating the app, the first thing you need to do is tell Feishu that it’s a bot.

In the left menu of the developer console, find “Add app capabilities”, then find the “Bot” card, and click Add. If you skip this step, all the permission setup that follows is wasted effort.

Step 2: Get the Raspberry Pi “running” first

Feishu’s long-connection mechanism requires: you must start the gateway locally first; only then can the Feishu backend successfully detect your long connection!

Run this in the Raspberry Pi terminal and leave it running:

Bash

picoclaw gateway

Step 3: Enable the “long connection” subscription mode

In the Feishu developer console, go to “Events and callbacks” in the left menu -> find “Subscription method”, and click the small edit icon next to it.

Select “Receive events via long connection (recommended)”, then save.

Step 4: Configure exactly 4 core permissions (no admin review needed)

In the left menu, go to “Permission management”. To get basic direct-message and group @-mention replies working, while trying to avoid triggering the complicated enterprise admin approval process, search for and enable only these 4 permissions (all under “app identity”):

im:message (get and send direct and group messages)
im:message.group_at_msg:readonly (receive @bot message events in group chats)
im:message.p2p_msg:readonly (read direct messages users send to the bot)
im:message:send_as_bot (send messages as the app)

For convenience, you can also copy the JSON below and import the permissions in bulk, which saves you from repeatedly applying for and enabling them:

{
  "scopes": {
    "tenant": [
      "contact:contact.base:readonly",
      "docx:document:readonly",
      "im:chat:read",
      "im:chat:update",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message.pins:read",
      "im:message.pins:write_only",
      "im:message.reactions:read",
      "im:message.reactions:write_only",
      "im:message:readonly",
      "im:message:recall",
      "im:message:send_as_bot",
      "im:message:send_multi_users",
      "im:message:send_sys_msg",
      "im:message:update",
      "im:resource",
      "application:application:self_manage",
      "cardkit:card:write",
      "cardkit:card:read"
    ],
    "user": [
      "contact:user.employee_id:readonly",
      "offline_access","base:app:copy",
      "base:field:create",
      "base:field:delete",
      "base:field:read",
      "base:field:update",
      "base:record:create",
      "base:record:delete",
      "base:record:retrieve",
      "base:record:update",
      "base:table:create",
      "base:table:delete",
      "base:table:read",
      "base:table:update",
      "base:view:read",
      "base:view:write_only",
      "base:app:create",
      "base:app:update",
      "base:app:read",
      "board:whiteboard:node:create",
      "board:whiteboard:node:read",
      "calendar:calendar:read",
      "calendar:calendar.event:create",
      "calendar:calendar.event:delete",
      "calendar:calendar.event:read",
      "calendar:calendar.event:reply",
      "calendar:calendar.event:update",
      "calendar:calendar.free_busy:read",
      "contact:contact.base:readonly",
      "contact:user.base:readonly",
      "contact:user:search",
      "docs:document.comment:create",
      "docs:document.comment:read",
      "docs:document.comment:update",
      "docs:document.media:download",
      "docs:document:copy",
      "docx:document:create",
      "docx:document:readonly",
      "docx:document:write_only",
      "drive:drive.metadata:readonly",
      "drive:file:download",
      "drive:file:upload",
      "im:chat.members:read",
      "im:chat:read",
      "im:message",
      "im:message.group_msg:get_as_user",
      "im:message.p2p_msg:get_as_user",
      "im:message:readonly",
      "search:docs:read",
      "search:message",
      "space:document:delete",
      "space:document:move",
      "space:document:retrieve",
      "task:comment:read",
      "task:comment:write",
      "task:task:read",
      "task:task:write",
      "task:task:writeonly",
      "task:tasklist:read",
      "task:tasklist:write",
      "wiki:node:copy",
      "wiki:node:create",
      "wiki:node:move",
      "wiki:node:read",
      "wiki:node:retrieve",
      "wiki:space:read",
      "wiki:space:retrieve",
      "wiki:space:write_only"
    ]
  }
}

Go back to the “Events and callbacks” page and click the “Add event” button on the right.

Search for and select Receive messages (im.message.receive_v1).

Step 6: Publish a version (the crucial final step!)

Feishu’s strict rule: any permission or event you change will not take effect until you publish it!

In the left menu, go to “Version management and release” -> click “Create version” -> enter any version number (e.g. 1.0.0) -> save, then click “Request release”.

6. Running as a daemon (so it never goes offline)

The gateway you’re running in the terminal now will disconnect as soon as you close the terminal window. We need to turn it into a background “guardian” on the Raspberry Pi.

First press Ctrl + C in the Raspberry Pi terminal running picoclaw gateway to stop it. Then copy the whole block below in one go and press Enter to create a system service:

Bash

sudo tee /etc/systemd/system/picoclaw.service << 'EOF'
[Unit]
Description=PicoClaw Gateway Service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi
ExecStart=/usr/bin/picoclaw gateway
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

Activate and start the service (run these in order):

Bash

sudo systemctl daemon-reload
sudo systemctl enable picoclaw
sudo systemctl start picoclaw

From now on, if you want to see the AI’s runtime logs, just run:

Bash

journalctl -u picoclaw -f

7. Troubleshooting common problems (FAQ)

Q: When I log in via SSH, I get Host key verification failed and a screenful of uppercase warnings?

Cause: You may have assigned the Raspberry Pi an IP address that was previously used by another device, and your computer’s security mechanism thinks it has encountered an impersonator.
Fix: In your computer’s terminal (note: not on the Raspberry Pi), run ssh-keygen -R <the Raspberry Pi's IP address> to remove the old entry.

Q: When I start the gateway, I get feishu channel is not supported on 32-bit?

Cause: The Raspberry Pi system was installed incorrectly (as a 32-bit system), or your Raspberry Pi board is too old (such as an old Zero W) and doesn’t support 64-bit at all.
Fix: Switch to a 3B or newer board and re-flash a 64-bit system with Imager.

Q: The terminal shows HEARTBEAT_OK, but messages sent in Feishu get no response, and the terminal shows no receive logs either?

Cause: The LLM API connection works, but the Feishu server isn’t pushing messages to you.
Fix: Go back to Section 5 of the tutorial and focus on checking whether you added the “receive message” event, and be sure to publish a new version.

(End of article)

Become Siri: A Raspberry Pi Physical Walkie-Talkie Evolution Guide

Sun, 08 Mar 2026 00:00:00 +0000

1. Architecture: Single Source of Truth

To build a voice assistant on a severely resource-constrained Raspberry Pi, this design abandons the traditional continuously-listening daemon model and instead adopts a geeky “event-driven + direct CLI calls” architecture.

One brain, many endpoints: A Python script hijacks the physical button and audio peripherals, calling picoclaw agent’s in single-run (CLI) mode directly on the local machine. This means the physical walkie-talkie on the desk and the Feishu (a Chinese workplace collaboration app) bot in the cloud share the same LLM brain, the same Feishu credentials and context, and the same local sandbox workspace (~/.picoclaw/workspace).
Extremely lightweight: The low-level components wake up only at the moment the button is pressed. After the button is released, the audio stream quickly passes through Volcano Engine (STT) -> local PicoClaw (LLM) -> Microsoft Azure (TTS), with very low memory usage throughout.

2. Key Pitfalls and Fixes

In this cross-domain work connecting low-level hardware audio to the LLM’s plain text, we hit and solved these very subtle hidden system-level pitfalls:

2.1 The Physical Button’s “Ghost Repeated Presses” (Mechanical Bouncing)

Symptom: A one-second press made the program report [系统忙碌] (system busy) countless times, and even got the recording process killed instantly, causing a fatal error.
Solution: This came from the physical bounce of the arcade button’s metal microswitch. During gpiozero initialization, we explicitly set the hardware debounce parameter bounce_time=0.3, so the system ignores all spurious signals within 300 milliseconds.

2.2 Audio Lockup and “Swallowed Words” (Buffer Overrun)

Symptom: Frequent overrun!!! (buffer overflow) errors, or the first one or two words of every utterance (such as “Beijing”) always getting missed; and even after the script crashed, zombie processes could leave the microphone permanently locked.
Solution:
1. Startup nuclear cleanup: Added killall -9 arecord mpg123 at the top of the Python script to force-kill orphan processes on every launch, so the sound card is completely clean.
2. Very large buffer: Added the --buffer-time=250000 parameter to arecord, completely eliminating frame-drop warnings.
3. Visual foolproofing: Turn on the LED after a delay. After the low-level hardware has been powered on and stable for 0.5 seconds, the light comes on to prompt the user to speak, which perfectly avoids the “swallowed words” window during hardware cold start.
4. Graceful release: When stopping recording, use send_signal(signal.SIGINT) instead of calling terminate(), ensuring the end of the WAV file is properly closed and the ALSA hardware lock is released.

2.3 “Mental Pollution” in LLM Output and TTS Crashes

Symptom: PicoClaw’s CLI output included lots of ASCII art logos and [INFO] system logs; and the LLM would sometimes output emoji such as 🦞 or Markdown tables, causing the edge-tts speech synthesis engine to crash and stop working.
Solution:
1. Layered stripping: Split the output by line and discard everything before the last [INFO] log line.
2. Regex cleaning: Before sending to the speech engine, use the regex re.sub to aggressively strip all non-Chinese/English characters and basic punctuation, ensuring smooth and natural speech playback.

2.4 “Time Hallucinations” Across Time Zones

Symptom: The LLM has no concept of system time and makes wild guesses when asked about “tomorrow.”
Solution: System Prompt Injection. When the Python script assembles the query text, it uses the datetime module to calculate US Eastern Time and Beijing Time in real time, and forcibly prepends them as [系统隐藏设定] (hidden system settings) before the user’s voice input. This not only eliminates hallucinations but also gives the LLM the ability to handle business across two time zones perfectly.

2.5 Installing Dependencies

After reflashing the Raspberry Pi (e.g., switching to the latest Debian 12 Bookworm Lite), the original environment is completely wiped. Follow these steps in order, and the walkie-talkie will be back up and running within 5 minutes.

2.5.1 Installing Low-Level System Software

Update the package lists and install the basic audio-processing and process-management tools, plus the Python package manager:

sudo apt update
# Install audio player (mpg123), recording driver set (alsa-utils), process force-kill tool (psmisc), and pip3
sudo apt install -y mpg123 alsa-utils psmisc python3-pip

2.5.2 Installing Core Python Driver Libraries

Use pip3 to install the required third-party libraries. (Note: In the latest Raspberry Pi OS, the system restricts direct use of pip to protect the global environment; you must append the --break-system-packages parameter to force-install into the user directory):

pip3 install requests gpiozero edge-tts --break-system-packages

2.5.3 Fixing the Environment Variables (Resolving the “Command Not Found” Warning)

The edge-tts installed in the previous step goes into a hidden user-level binary directory. You need to add it to the system PATH:

# Append the user's private bin directory to PATH and write it to the bash config file
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
# Make the config take effect immediately
source ~/.bashrc

Verification test: Type edge-tts --version in the terminal; if it prints the version number, the configuration worked.

2.5.4 Restoring the PicoClaw Core and Workspace

We need to put the walkie-talkie’s brain back:

Main program in place: Move the compiled picoclaw binary to /usr/local/bin/ and make it executable (sudo chmod +x /usr/local/bin/picoclaw).
Rebuild the workspace: Recreate the ~/.picoclaw/workspace/ directory and copy the previously backed-up skills folder (such as the Feishu and search plugins) and configuration files back exactly as they were.

2.5.5 Hardware Sound Card Recovery (Easy to Miss)

On a clean system, an external I2S microphone array (such as the Google Voice HAT) is in a physically muted state by default:

Remount the driver: Modify /boot/firmware/config.txt per the official documentation to enable I2S, and configure the ~/.asoundrc file.
Unmute the low-level controls and set the volume:

alsamixer

Press F4 to switch to the Capture screen, select the microphone, press Space to clear the MM (muted) state, and raise the gain.
Press F3 to switch to the Playback screen, and use the arrow keys to lower the playback volume to 40%–50% to avoid distortion.

Persist the volume configuration: Run sudo alsactl store to ensure the volume settings are not lost after a reboot.

At this point, the software and hardware environment has been fully restored. Combined with the Systemd daemon configuration, the system can go back to running fully automatically.

3. Complete Integration Script (`walkie_talkie.py`)

This script already includes all the bulletproof safeguards, timezone injection, and exception handling, and can run directly as a production daemon.

import subprocess
import os
import requests
import threading
import base64
import uuid
import re
import time
import signal
from datetime import datetime, timezone, timedelta
from gpiozero import Button, LED
from signal import pause

print("🧹 Cleaning up any leftover low-level audio processes...")
# Force-kill leftover processes before startup to release the ALSA hardware lock
subprocess.run(["killall", "-q", "-9", "arecord", "mpg123", "edge-tts"], stderr=subprocess.DEVNULL)

# ================= 1. Hardware and path configuration =================
BUTTON_PIN = 23
LED_PIN = 25

# Use PicoClaw's official standard workspace
WORKSPACE = os.path.expanduser("~/.picoclaw/workspace")
os.makedirs(WORKSPACE, exist_ok=True)
AUDIO_IN = os.path.join(WORKSPACE, "voice_in.wav")
AUDIO_OUT = os.path.join(WORKSPACE, "voice_out.mp3")

# ================= 2. Volcano Engine (turbo large-model STT) configuration =================
VOLC_APPID = "replace_with_your_APP_ID"  
VOLC_TOKEN = "replace_with_your_ACCESS_TOKEN"

# ================= 3. Global state initialization =================
# Core: bounce_time=0.3 handles physical button bounce
button = Button(BUTTON_PIN, bounce_time=0.3)
led = LED(LED_PIN)
record_proc = None
is_processing = False  # concurrency lock

def start_recording():
    global record_proc, is_processing
    if is_processing:
        print("⏳ [System busy] Still processing the previous command...")
        return
        
    if os.path.exists(AUDIO_IN):
        os.remove(AUDIO_IN)
        
    print("\n⏳ [Preparing] Waking up the microphone base...")
    
    # --buffer-time=250000 fixes overruns; DEVNULL suppresses interrupt errors
    cmd = ["arecord", "--buffer-time=250000", "-f", "S16_LE", "-r", "16000", "-c", "1", AUDIO_IN, "-q"]
    record_proc = subprocess.Popen(cmd, stderr=subprocess.DEVNULL)

    # Delay turning on the LED: let the hardware power up and stabilize so the first word isn't swallowed
    time.sleep(0.5)
    led.on()
    print("🟢 [Recording] Microphone ready. Speak, then release to stop...")

def stop_recording():
    global record_proc, is_processing
    if is_processing or record_proc is None:
        return
        
    # Small buffer before stopping so the tail isn't cut off
    time.sleep(0.3)
    # Use SIGINT to exit gracefully, ensuring the WAV header is written and the sound card is released
    record_proc.send_signal(signal.SIGINT)
    record_proc.wait()
    record_proc = None
    
    led.off()
    print("🛑 [Released] Recording ended; handing it off to the processing center...")
    
    is_processing = True
    threading.Thread(target=process_audio_pipeline).start()

def process_audio_pipeline():
    global is_processing
    led.blink(on_time=0.5, off_time=0.5) 

    try:
        if not os.path.exists(AUDIO_IN):
            print("❌ Fatal error: the recording file was not created!")
            return
            
        # ================= STT (Volcano Engine turbo recognition) =================
        print("🔄 Requesting Volcano Engine STT...")
        user_text = ""
        try:
            with open(AUDIO_IN, "rb") as audio_file:
                base64_audio = base64.b64encode(audio_file.read()).decode('utf-8')
            
            headers = {
                "X-Api-App-Key": VOLC_APPID,
                "X-Api-Access-Key": VOLC_TOKEN,
                "X-Api-Resource-Id": "volc.bigasr.auc_turbo",
                "X-Api-Request-Id": str(uuid.uuid4()),
                "X-Api-Sequence": "-1",
                "Content-Type": "application/json"
            }
            payload = {
                "user": {"uid": VOLC_APPID},
                "audio": {"data": base64_audio},
                "request": {"model_name": "bigmodel"}
            }
            
            recognize_url = "https://openspeech.bytedance.com/api/v3/auc/bigmodel/recognize/flash"
            response = requests.post(recognize_url, json=payload, headers=headers, timeout=10)
            
            status_code = response.headers.get("X-Api-Status-Code")
            if status_code == '20000000':
                user_text = response.json().get("result", {}).get("text", "")
                if not user_text: user_text = "I heard something, but couldn't make out the words."
            elif status_code == '20000003': user_text = "It sounds like you didn't say anything."
            else: user_text = "My ears are on strike for now."

        except Exception as e:
            user_text = "Network connection failed."

        print(f"👤 You said: {user_text}")

        # ================= AI thinking (PicoClaw dispatch center) =================
        print("🧠 Waking up the local PicoClaw process...")
        try:
            # Inject both time zones dynamically to prevent time hallucination
            utc_dt = datetime.now(timezone.utc)
            us_east_dt = utc_dt.astimezone(timezone(timedelta(hours=-4)))
            beijing_dt = utc_dt.astimezone(timezone(timedelta(hours=8)))
            
            weekdays = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]
            time_context = f"[Current system time: US Eastern {us_east_dt.strftime('%m-%d %H:%M')}({weekdays[us_east_dt.weekday()]}) | Beijing {beijing_dt.strftime('%m-%d %H:%M')}({weekdays[beijing_dt.weekday()]})]"
            
            # Build the prompt with the tool-dispatch rules
            voice_prompt = f"""{time_context}
User command: "{user_text}"

[System-enforced rules (voice assistant mode)]:
1. [Minimal and fast] You are a capable, efficient personal voice assistant. Reply straight to the point, strictly under 100 characters and at most one or two sentences. (Note: the fewer the characters, the lower the system's voice response latency!)
2. [No AI tone] Give the answer directly! Never use robotic filler like "I found this for you", "according to my search" or "I tested it and found", and don't throw questions back at the user.
3. [Silent invocation] For things like traffic restrictions, weather and news, silently call the built-in tools, then state the key conclusion directly once you have the data.
4. [Clear pronunciation] Absolutely no Markdown (such as **, -, #), tables, numbered lists, Emoji or unusual symbols; output only plain Chinese characters and basic punctuation that can be read aloud smoothly."""

            cmd = ["picoclaw", "agent", "-m", voice_prompt]
            result = subprocess.check_output(cmd, text=True, stderr=subprocess.STDOUT)
            
            # Strip PicoClaw CLI's ASCII logo and system logs
            lines = result.split('\n')
            last_log_idx = -1
            for i, line in enumerate(lines):
                if "[INFO]" in line or "[WARN]" in line or "[ERROR]" in line:
                    last_log_idx = i
            
            if last_log_idx != -1 and last_log_idx < len(lines) - 1:
                ai_reply = "\n".join(lines[last_log_idx+1:]).strip()
            else:
                ai_reply = "\n".join([l for l in result.split('\n') if "██" not in l]).strip()

            if not ai_reply: ai_reply = "The brain finished but returned no text."
                 
        except Exception as e:
            ai_reply = "Failed to connect to the brain; please check that it's running."

        print(f"🤖 PicoClaw raw reply: {ai_reply}")
        
        # ================= TTS and audio playback =================
        print("🔊 Cleaning text and synthesizing speech...")
        
        # Final cleanup: strip Emoji and other illegal characters that would crash TTS
        clean_text = re.sub(r'[^\u4e00-\u9fa5A-Za-z0-9，。！？、！\?,\.～~]', '', ai_reply)
        if not clean_text: clean_text = "The reply has no readable text."

        tts_cmd = [
            "python3", "-m", "edge_tts", 
            "--text", clean_text, 
            "--voice", "zh-CN-XiaoxiaoNeural",
            "--write-media", AUDIO_OUT
        ]
        
        try:
            subprocess.run(tts_cmd, check=True, capture_output=True, text=True)
            led.on() 
            subprocess.run(["mpg123", AUDIO_OUT])
        except subprocess.CalledProcessError as e:
            print(f"❌ Speech generation failed!\nError details: {e.stderr}")
        
    except Exception as e:
        print(f"❌ Uncaught exception: {e}")
    finally:
        led.off() 
        is_processing = False
        print("✅ System reset; waiting for the next wake-up.")

button.when_pressed = start_recording
button.when_released = stop_recording

print("🚀 Geek walkie-talkie hub is ready!")
pause()

4. Final Deployment: Turning It into a Background Daemon (Daemonize)

To fully free this hardware assistant from the SSH terminal and achieve “plug it in and use it, and recover automatically after power loss or reboot,” we need to use Linux’s native systemd to register it as a system-level service.

⚠️ Pitfall warning: Never use rc.local or crontab to start audio-related scripts. Audio devices (sound.target) load slowly, and only systemd can precisely control startup order and restart the script automatically if it crashes unexpectedly.

4.1 Create the systemd service file

Assume your script is at /home/pi/walkie_talkie.py. Run the following command in the terminal to create the configuration file:

sudo nano /etc/systemd/system/picoclaw-voice.service

Paste the following into it (note: if your username is not pi, or the script path is different, change them accordingly):

[Unit]
Description=PicoClaw Voice Assistant (Hardware Gateway)
# Make sure this service starts after the network and the underlying sound card hardware are loaded
After=network.target sound.target

[Service]
Type=simple
# Must specify the pi user; otherwise, when run as root, the ~/.picoclaw path becomes /root/.picoclaw, causing all configuration to fail
User=pi
WorkingDirectory=/home/pi
ExecStart=/usr/bin/python3 /home/pi/walkie_talkie.py

# Crash auto-restart mechanism (try to restart every 5 seconds)
Restart=always
RestartSec=5

# [Extremely critical] Inject environment variables! Make sure the subprocess underneath the Python script can find picoclaw, edge-tts and arecord
Environment="PATH=/home/pi/.local/bin:/usr/local/bin:/usr/bin:/bin"
Environment="PYTHONUNBUFFERED=1"

[Install]
WantedBy=multi-user.target

Save and exit (in nano, press Ctrl+O -> Enter -> Ctrl+X).

4.2 Reload the system and set it to start on boot

Once the configuration is written, tell the system to reload the configuration and set the service to start on boot:

# 1. Reload the systemd daemon
sudo systemctl daemon-reload

# 2. Set to start automatically on boot
sudo systemctl enable picoclaw-voice.service

# 3. Start the service immediately
sudo systemctl start picoclaw-voice.service

4.3 Common management commands (quick reference)

Once it’s registered as a service, you can manage your walkie-talkie as gracefully as you would manage Nginx or MySQL:

Check the current status (seeing a green active (running) means it’s working): ```bash sudo systemctl status picoclaw-voice

* **Manually stop** the service:
```bash
sudo systemctl stop picoclaw-voice

Manually restart the service (after you modify the Python code, you must run this command for the changes to take effect): ```bash sudo systemctl restart picoclaw-voice

* **View logs in real time** (replaces the print output you would otherwise see in the terminal; essential for troubleshooting):
```bash
# -f means real-time scrolling, similar to tail -f
journalctl -u picoclaw-voice -f

Additional notes:

With this piece of the puzzle in place, your Raspberry Pi has become a complete “black-box appliance.” You can safely close the terminal on your computer, unplug the Raspberry Pi, move it to the living room or nightstand, and plug it in. After it boots, wait about one or two minutes (until the network and background processes finish loading), and then you can just press the button and talk to it!

Reviving and Configuring Google Voice Kit V1 Basic Hardware

Sun, 08 Mar 2026 00:00:00 +0000

Supported environment:

Hardware: Raspberry Pi + Google Voice Kit V1 (Voice HAT expansion board)
OS: Raspberry Pi OS (based on Debian Bookworm or newer, kernel 6.x+)

1. Enable the low-level hardware driver

The device tree config file on modern Raspberry Pi systems has moved to the /boot/firmware/ directory. You need to disable the default onboard audio and load the Voice HAT-specific driver.

Steps: Edit the config file:

sudo nano /boot/firmware/config.txt

Make these two changes:

Comment out the default audio line (if present):

#dtparam=audio=on

Append the Voice HAT device tree overlay directive to the end of the file:

dtoverlay=googlevoicehat-soundcard

Save and exit (Ctrl+O, Enter, Ctrl+X), then reboot the system:

sudo reboot

2. Verify the sound card and get the device number

After rebooting, confirm that the system has correctly detected the Voice HAT hardware.

Steps: List the audio devices:

aplay -l

Expected output: Look for an entry that contains snd_rpi_googlevoicehat_soundcard. Note the corresponding card number (e.g. card 1 or card 0). The configuration below uses card 1 as an example.

3. Configure global ALSA audio routing

By defining a user-level ALSA config file, you force the system to use the Voice HAT as the global default audio input/output device, and use the plug plugin to handle audio resampling automatically.

Steps: Create or edit the ALSA configuration file for the current user:

nano ~/.asoundrc

Write the following configuration (make sure to replace the 1 in hw:1,0 and card 1 with the actual card number obtained in the previous step):

pcm.!default {
    type plug
    slave.pcm "hw:1,0"
}

ctl.!default {
    type hw
    card 1
}

Save and exit. The system’s basic audio layer is now configured.

4. Install dependencies and write the MVP script

The Voice HAT’s button and LED are connected directly to the Raspberry Pi’s standard GPIO pins (button = GPIO 23, LED = GPIO 25). Use the gpiozero library to control them.

Steps: Install the necessary Python dependencies:

sudo apt update
sudo apt install python3-gpiozero

Create the test script:

nano voice_mvp.py

Enter the following code:

from gpiozero import Button, LED
from signal import pause
import subprocess

# Voice HAT V1 hardware pin definitions
BUTTON_PIN = 23  
LED_PIN = 25     
# System audio file for testing
AUDIO_FILE = "/usr/share/sounds/alsa/Front_Center.wav" 

button = Button(BUTTON_PIN)
led = LED(LED_PIN)

def on_button_pressed():
    print("[Event] Button Pressed")
    led.on()
    
    try:
        # Since ~/.asoundrc is already configured, no device parameters are needed here
        subprocess.run(["aplay", AUDIO_FILE])
    except Exception as e:
        print(f"[Error] Audio playback failed: {e}")
        
    led.off()
    print("[Status] Playback complete. Awaiting next trigger.")

# Bind the button event
button.when_pressed = on_button_pressed

print("[System] Initialization complete. Listening for hardware interrupts...")
pause()

5. Run the test

Run the script:

python3 voice_mvp.py

Test criteria: Press the physical button on top of the device; the LED indicator lights up, the speaker plays the “Front Center” audio, then the LED turns off and the terminal prints the corresponding log messages.

10 Core Tips for Boosting Efficiency in Claude Code

Sat, 07 Feb 2026 00:00:00 +0000

10 Core Tips for Improving Efficiency in Claude Code

Claude Code is a powerful CLI tool released by Anthropic. After using it extensively, I’ve summarized the following 10 core tips that can significantly speed up your work.

1. Switch between run modes easily

Press shift + tab to quickly switch between three modes:

Default mode (? for shortcuts): The most cautious; asks you before modifying files.
Auto mode (accept edits on): Modifies files automatically, good for quick fixes.
Plan mode (plan mode on): Only discusses the plan and doesn’t modify files, good for early-stage planning.

2. Terminal commands and background tasks

Before you enter a prompt, type ! to run a local shell command directly.
Use ⌃ + b to send an already running task (such as npm run dev) to the background while you continue talking to Claude.
Type /tasks to view background tasks; once inside, press k to close the selected task.

3. Multi-line prompt editing

If you need to type a long, complex prompt, press ⌃ + g to open a temporary file in VS Code for editing; when you save, it syncs back to the terminal automatically.

4. Sudo mode, fully unleashed

If you’re confident in your system’s security and want maximum efficiency, you can use: claude --dangerously-skip-permissions In this mode, Claude no longer asks before creating or modifying files or running commands. Very powerful, but use it with care.

5. Graceful rollback and management

Claude Code can’t roll back perfectly (for example, newly created files can’t be undone), so I recommend using it together with Git.

/rewind: Undo the last action.
Press esc twice: Enter interactive rollback selection mode.

6. A small trick for uploading images

Simply drag and drop the image file into the terminal window.
On macOS, even images copied with command + c have to be pasted into the terminal with ctrl + v.

7. Resuming sessions

Inside Claude Code: /resume.
From outside Claude Code, go straight back into the last session: claude -c.

8. Context compression and cleanup

When the context gets too long and responses slow down or token usage gets too high:

/compact [optional description]: Compress the current context. Afterwards, press ⌃ + o to view the compressed result.
/clear: Completely clear the current session context.

9. Build system-level memory

With the /init command, Claude creates a CLAUDE.md file in the current directory. The instructions and project rules in this file are read automatically each time a conversation starts.

10. Managing your personal preferences (`/memory`)

Type /memory to set:

Project memory: For the current project (saved in ./CLAUDE.md).
User memory: Applies globally (saved in ~/.claude/CLAUDE.md), a good place for your personal coding habits and background.

I hope these tips help you get a better handle on Claude Code and add a little sunshine to your development life.

My a6400 HLG Grading Workflow for FCPX

Wed, 10 Jan 2024 00:00:00 +0000

Sony’s straight-out-of-camera colors aren’t pleasing enough, and when grading, you need to handle things differently depending on the mode you chose when shooting. Most online examples use sLog2 or sLog3 for grading; the dynamic range is higher, but there may also be more work to do in post. Maybe applying a conversion LUT can get you a quick result, but that’s beyond the scope of this article. This article mainly focuses on the workflow for HLG mode.

HLG shooting mode

The advantage of HLG shooting mode is that, even straight out of camera, it can still offer a wider color range than normal out-of-camera footage (such as cine). Since the color space becomes BT.2020, when we import this footage into FCPX, we need to convert the color space, otherwise it will look overexposed.

You get HLG mode by changing the picture profile (pp value) in the MR position:

Color grading workflow

Convert color space (newer versions of FCPX automatically turn on Color Conform to convert from HLG to Rec.709 for us)

Primary grading

Basic white balance: you can use balance color to easily fix the color balance; if the result isn’t ideal, find balance color in the inspector panel, switch from automatic to manual mode, and use the eyedropper to pick a white point in the frame.

Advanced white balance: use the color curve and color wheel together with the waveform scope to make manual adjustments. The goal is to make the red, green and blue in the waveform overlap as much as possible and turn white. But it still depends on the actual frame; for example, skin tones will have a bit more red, which is normal.

Exposure: pull the highlights to near 100 and the shadows to near 0, then adjust the midtones based on the image. If you run into a high-contrast situation, such as a very bright sky but a very dark subject, you can use the hue/saturation curves to select the bright areas based on luma, pull back the overexposed areas, and then continue adjusting the whole image.

Saturation: adjust to taste, but I suggest not pushing it too far from the center of the vectorscope, to leave some room for secondary grading.

Secondary grading, aka applying a LUT

This step is the simplest: find a LUT you like and drag it onto the clip. If the effect is too strong, you can fix that by adjusting the mix percentage.

Restoring skin tones

After secondary grading, skin tones may become distorted. We need to drag to select the skin area (or the orange area at the bottom) in the Hue/Saturation Curves and adjust the skin tone so it sits as close as possible to the 10:30 line.

HUE vs HUE: changes the color of the selected color range; HUE vs SAT: changes the saturation of the selected color range; HUE vs LUMA: changes the luma of the selected color range; LUMA vs SAT: changes the saturation of the selected luma range; SAT vs SAT: changes the saturation of the selected saturation range; ORANGE vs SAT: changes the saturation of the orange range (similar to skin tones).

If other colors are the same as the skin tone, you’ll also need to create a mask to make sure that when we adjust the skin tone, we don’t change the color of other objects.

24/7 Livestreaming with a Raspberry Pi

Mon, 10 Apr 2023 00:00:00 +0000

Recently I wanted to loop the videos from my “10-minute piano practice series” on a live streaming platform, and at first I planned to do it with a cloud server. But the Raspberry Pi that had been gathering dust at home said: “Just leave this to me, and it won’t cost you a cent!” And that’s how this came about.

Live stream link

http://live.bilibili.com/3544257

Connecting to the Raspberry Pi over SSH

$ ssh pi@192.168.x.x

# default password raspberry

Uploading the video files

Upload the videos from your local computer to the /home/pi/Videos/ folder on the Raspberry Pi:

$ scp video.mp4 pi@192.168.x.x:/home/pi/Videos/

Core code for looping playback

Create an executable file named stream.sh in the /home/pi/ directory and paste in the following contents:

#!/bin/bash

RTMP_URL="rtmp://live-push.bilivideo.com/live-bvc/?streamname=example"
VIDEO_DIR="/home/pi/Videos"

while true; do
  for VIDEO_FILE in $VIDEO_DIR/*.mp4; do
    ffmpeg -re -i "$VIDEO_FILE"\
           -c:v copy -c:a aac \
           -b:a 192k -strict -2 \
           -f flv $RTMP_URL
  done
done

It’s really just using ffmpeg to push the live stream. You’ll need to get the RTMP_URL here yourself from the streaming platform you’re using. The -c:v copy means the Raspberry Pi doesn’t have to decode the video again, since its performance is pretty modest. I’d suggest processing the videos ahead of time with HandBrake or some other format conversion tool; I processed mine at 720p with Constant Quality set to 30.

Finally, don’t forget to change the file permissions, otherwise the process manager won’t be able to run it:

$ chmod +x stream.sh

Process manager

Using supervisorctl makes it easy to run it in the background, so even if we close the current terminal session, the stream keeps running. If you don’t have it yet, install it first:

sudo apt install supervisor

Here are a few common control commands:

sudo supervisorctl start play
sudo supervisorctl stop play
sudo supervisorctl status

Configuring paths and content

It covers the working directory, the script to run, the fault-tolerance mechanism, and log storage.

/etc/supervisor/conf.d/play.conf

[program:play]
directory=/home/pi
command=./stream.sh
autostart=true
autorestart=true
startretries=10
redirect_stderr=true
stdout_logfile=/home/pi/stream.log
stdout_logfile_maxbytes=512KB
stdout_logfile_backups=2
environment=ASPNETCORE_ENVIRONMENT="Development"

For Audiobook Lovers: Convert Ebooks to MP3 with Python

Fri, 07 Apr 2023 00:00:00 +0000

Prerequisites

An ebook in .txt format
Internet access
edge-tts installed $ pip install edge-tts
Python 3 installed

Basic usage

$ edge-tts --text "Hello, world!" --write-media hello.mp3 --write-subtitles hello.vtt

For more usage, see Edge-tts Usage.

Using Python to split the ebook into small chapters

Suppose we have an ebook named “白鹿原.txt” (White Deer Plain). In the same directory as the ebook, create a file named “split.py” and paste the code below into it.

# Open the ebook
with open("白鹿原.txt", "r") as input_file:
    # Read the contents of the ebook
    file_contents = input_file.read()
    
    # Use "\n\n第" to separate the chapters (different ebooks have different structures, confirm the separator manually)
    file_chunks = file_contents.split("\n\n第")
    
    # Split the ebook
    for i, file_chunk in enumerate(file_chunks):
        # Name the output ebook
        output_filename = f"白鹿原_{i+1}.txt"
        
        # Open the output ebook
        with open(output_filename, "w") as output_file:
            # Write the split content and print the result in the command line
            output_file.write("第" + file_chunk)
            print("\n finishing %s" % output_file)

# Done
print ("done.")

Using edge-tts to convert the chapters to mp3

Put all the chapter .txt files you output into a folder named “splitted”. In that folder, create a file named “txt_to_audio.py” and paste the code below into it:

import os
import subprocess

# Specify the working directory and output folder
txt_path = "./"
output_folder = "output"

# Create the output folder
if not os.path.exists(output_folder):
    os.makedirs(output_folder)

# Iterate over all txt files in the directory
for txt_file in os.listdir(txt_path):
    # Check whether it is a txt file
    if txt_file.endswith(".txt"):
        # Create the terminal command (see the edge-tts command)
        cmd = f"edge-tts -f {txt_path}/{txt_file} --write-media {output_folder}/{txt_file[:-4]}.mp3 --write-subtitles {output_folder}/{txt_file[:-4]}.vtt --voice zh-CN-XiaoxiaoNeural --rate=+10%"
        # Execute the terminal command and print the status
        print('file %s is being processed...' % txt_file)
        subprocess.run(cmd, shell=True)
        print('file %s completed.' % txt_file)

Wait for it to finish

This uses online text-to-speech technology. Just wait for the task to finish, and you’ll have the mp3 files.

List of available languages

Only Chinese and English are included here; see here for the full list:

$ edge-tts --list-voices

Name: zh-CN-XiaoxiaoNeural (versatile)
Gender: Female

Name: zh-CN-XiaoyiNeural
Gender: Female

Name: zh-CN-YunjianNeural
Gender: Male

Name: zh-CN-YunxiNeural
Gender: Male

Name: zh-CN-YunxiaNeural
Gender: Male

Name: zh-CN-YunyangNeural (steady)
Gender: Male

Name: zh-CN-liaoning-XiaobeiNeural
Gender: Female

Name: zh-CN-shaanxi-XiaoniNeural
Gender: Female

Name: zh-HK-HiuGaaiNeural
Gender: Female

Name: zh-HK-HiuMaanNeural
Gender: Female

Name: zh-HK-WanLungNeural
Gender: Male

Name: zh-TW-HsiaoChenNeural
Gender: Female

Name: zh-TW-HsiaoYuNeural
Gender: Female

Name: zh-TW-YunJheNeural
Gender: Male

Name: en-US-AnaNeural (child voice)
Gender: Female

Name: en-US-AriaNeural
Gender: Female

Name: en-US-ChristopherNeural
Gender: Male

Name: en-US-EricNeural
Gender: Male

Name: en-US-GuyNeural
Gender: Male

Name: en-US-JennyNeural
Gender: Female

Name: en-US-MichelleNeural
Gender: Female

Name: en-US-RogerNeural
Gender: Male

Name: en-US-SteffanNeural
Gender: Male

Quickly Create a Countdown in After Effects

Wed, 15 Jun 2022 00:00:00 +0000

Reference: After Effects Tutorial - Creating a Countdown Timer Using Expressions

Core code

slider = thisComp.layer("Slider Control").effect("Slider Control")("Slider");

sec = Math.floor(slider%60);
min = Math.floor(slider/60);

function zero(x) {
	
if (x<10) return "0" + x
		
else return x
		
}
	
zero(min) + ":" + zero(sec)

Steps

Create a new Null layer, name it Slider Control, and add a “Slider Control” property.
Create a new text layer.
In the text layer, Alt+left-click “Source Text” and paste the core code into it.
Alt+left-click the Slider Control property on the Null layer and enter value - time;
Adjust the value of the Slider Control property on the Null layer; the value = the number of minutes you want for the countdown x 60. For example, for a 10-minute countdown, enter 600, i.e., 10x60.