{"id":1100,"date":"2026-07-06T13:16:42","date_gmt":"2026-07-06T13:16:42","guid":{"rendered":"https:\/\/guoh.ai\/lifelog\/?p=1100"},"modified":"2026-07-06T20:24:28","modified_gmt":"2026-07-06T20:24:28","slug":"dialf-drive-a-real-phone-from-your-terminal","status":"publish","type":"post","link":"https:\/\/guoh.ai\/lifelog\/2026\/07\/dialf-drive-a-real-phone-from-your-terminal\/","title":{"rendered":"DialF: Drive a Real Phone From Your Terminal"},"content":{"rendered":"
*A small tool that lets a script place real phone calls, talk, listen, and hang up \u2014 on a real SIM, over a real cellular network.*\n\n—\n\n## Why we built this\n\nAI voice agents are everywhere now \u2014 and they **live and die by latency and audio quality.** A second of dead air, a stiff robotic voice, or choppy, fluctuating audio is the difference between "sounds human" and "obviously a bot." Yet before every release we were measuring those things *by hand*: dial in, read a script, listen for gaps, do it again on the next build. It didn't scale, and "sounds fine to me" is not a regression test.\n\nWhat we actually needed was to automate a *real* phone call. Not a VoIP call. Not a simulator. An actual call on an actual carrier \u2014 the kind that rings a normal phone, goes through the normal network, and behaves exactly like a human dialing. So we could:\n\n– **Test phone systems end to end** \u2014 voice agents, IVRs, call centers, voicemail \u2014 the way a real caller experiences them.\n– **Run scripted conversations** \u2014 play a prompt, wait for the other side to finish talking, play the next one.\n– **Record both sides cleanly, on one timeline**, so we could measure **latency** ("how long after I speak does the other side respond?") \u2014 as a number, on every build.\n\nThe catch: **Android won't let an app record or inject the audio of a cellular call.** That path is locked to the system. So a pure software approach is impossible.\n\nDialF's answer is simple and a little old-school: **bridge the call audio through a real USB sound card.** The phone does the dialing; a sound card plays into the phone's mic and listens on its earpiece. Your computer drives the whole thing \u2014 and we know you'll wire your own AI agents up to do the driving.\n\n—\n\n## Why not a programmable 4G module?\n\nIt's the first thing every engineer suggests, and it's a fair instinct \u2014 a cellular module takes a SIM, speaks AT commands, and dials from a script. Cheap, headless, no human in the loop.\n\nBut a module isn't a phone. It carries its own compatibility quirks and behaves in ways real handsets don't \u2014 so it can quietly alter the very thing you're trying to measure. You end up testing the module's behavior, not your users' calls.\n\nThat's the crux: **a voice agent's audio path *is* the product, and a module only tests a synthetic version of it.** Your agent can sound flawless through a module and still ship stutter and echo through a real earpiece \u2014 and the module never warns you, because it was never on the path your callers actually hear. DialF drives a real phone for exactly that reason.\n\n—\n\n## What it does\n\nDialF turns a phone into something you can script:\n\n– \ud83d\udcde **Make, answer, reject, and hang up calls** \u2014 on the phone's own SIM.\n– \ud83d\udcac **Send and read SMS**, read the **call log** and **SIM list** (dual-SIM aware).\n– \ud83c\udf9b\ufe0f **Carrier controls** \u2014 toggle voicemail, run raw MMI\/USSD codes.\n– \ud83d\udde3\ufe0f **Scripted voice conversations** \u2014 play audio prompts, and *wait for the person to stop talking* using voice-activity detection before moving on.\n– \ud83c\udf99\ufe0f **Record the call** full-duplex \u2014 your audio (`tx`), their audio (`rx`), and a **stereo mix** (left = you, right = them), all the same length and sample-aligned (great for latency analysis).\n\nYou drive all of it from one command-line tool, or from a small YAML script.\n\n—\n\n## How it works\n\nDialF has two parts that talk to each other, plus a deliberate split between **control** and **audio**:\n\n“`mermaid\nflowchart TB\n subgraph Host["Your computer"]\n CLI["dialf (CLI)"]\n D["dialfd (daemon)"]\n Card["USB sound card"]\n end\n subgraph Android["Android phone"]\n App["DialF Phone app"]\n end\n\n CLI –>|commands| D\n D <–>|"WiFi \u00b7 WebSocket"| App\n D <–>|"audio in \/ out"| Card\n Card <–>|"headset cable"| App\n App –>|"dials \/ answers on its SIM"| Net(("Cellular network"))\n“`\n\n– **Control plane (over WiFi):** the `dialf` CLI sends commands to the `dialfd` daemon, which relays them to the **DialF Phone** app over a WebSocket. This is how dial \/ answer \/ SMS \/ hang up happen. No audio travels here.\n– **Audio plane (physical):** call audio flows through a **USB sound card** wired to the phone's headset jack. The card plays *into* the phone's microphone and records *from* its earpiece. The app just routes the call to the wired headset.\n\nWhy the split? Because Android blocks call-audio capture in software \u2014 so audio has to be bridged physically, never over WiFi.\n\n### A scripted call, step by step\n\n“`mermaid\nsequenceDiagram\n participant CLI as dialf CLI\n participant D as dialfd\n participant P as DialF Phone\n participant F as Far end\n\n CLI->>D: run call-script.yaml\n D->>P: dial +1…\n P->>F: ringing\u2026\n F–>>P: answers\n P–>>D: call active\n Note over D: call.wait_answered satisfied\n D->>P: play prompt (out the sound card \u2192 phone mic)\n P->>F: far end hears the prompt\n F–>>P: spoken reply (phone earpiece \u2192 sound card)\n P–>>D: reply audio captured\n Note over D: VAD waits for the reply to finish\n D->>P: play next prompt \u2026 then hang up\n“`\n\n—\n\n## How to use it\n\n### 1. Install the CLI (macOS or Linux)\n\n“`sh\nnpm install -g @agora-build\/dialf\n# or: curl -fsSL https:\/\/dl.agora.build\/dialf\/install.sh | bash\n“`\n\nThen start the background daemon:\n\n“`sh\ndialf service install –user # runs dialfd at login\n“`\n\n> On a Mac or laptop, keep `–user` \u2014 it runs as you, when you log in (needed so it can reach the sound card and mic). Use plain `dialf service install` (with `sudo`) only on a headless Linux server that should start at boot.\n\n### 2. Install the phone app\n\nSideload the APK on the Android phone (Android 9+):\n\n– **Latest release (default):** <https:\/\/github.com\/Agora-Build\/DialF\/releases>\n– or <https:\/\/dl.agora.build\/dialf\/dialf-phone-latest.apk>\n\nOpen it, grant phone\/SMS permissions, and **set it as the default dialer** (that's what lets it place and track calls).\n\n### 3. Pair them\n\nIn the app, enter the same **shared key** as your `dialfd` config and tap **Start service**. The phone finds the daemon automatically on your WiFi (mDNS). Confirm it's connected:\n\n“`sh\ndialf devices # your phone should appear\n“`\n\n### 4. Drive it\n\n“`sh\ndialf call dial <phone> +15551234 # place a call\ndialf call hangup <phone> # hang up\ndialf sms send <phone> +15551234 "hi" # send a text\ndialf call list <phone> –human # read the call log\ndialf –version # CLI + daemon versions\n“`\n\n### 5. Script a conversation\n\nJobs are plain YAML \u2014 a list of steps run in order:\n\n“`yaml\n– type: call.dial\n number: "+15551234"\n– type: call.wait_answered # wait for a real answer, not a fixed timer\n timeout_ms: 30000\n– type: audio.play # inject a prompt into the call\n file: samples\/prompt-en-1.wav\n– type: audio.wait_for_speech # listen until the other side stops talking\n end_timeout_ms: 45000\n silence_duration_ms: 3000\n– type: sms.send\n to: "+15551234"\n body: "thanks!"\n– type: call.hangup\n“`\n\n“`sh\ndialf run call-script.yaml\n“`\n\n`audio.wait_for_speech` is the clever bit: it runs voice-activity detection on the incoming audio, so the script moves on **when the person actually finishes speaking** \u2014 not after a guess.\n\n—\n\n## Recording and latency\n\nIf you turn on recording, every call is written as **three aligned WAV files**:\n\n– `\u2026-tx.wav` \u2014 what you sent (your prompts), mono\n– `\u2026-rx.wav` \u2014 what the far end said, mono\n– `\u2026-mix.wav` \u2014 **stereo**: left = tx (you), right = rx (them), so the two voices stay separated (swap with `mix_channels: rx_tx`)\n\nThey're captured on a **single clock**, so they line up sample-for-sample. That makes latency measurable: cross-correlate `tx` against `rx` and the offset is your round-trip delay.\n\n“`mermaid\nflowchart LR\n TX["tx.wav \u00b7 your prompt"] –> MIX["mix.wav \u00b7 stereo \u00b7 L=tx R=rx"]\n RX["rx.wav \u00b7 far-end reply"] –> MIX\n TX -.->|"cross-correlate"| RX\n RX –> L["latency = the lag between them"]\n“`\n\n—\n\n## Wrapping up\n\nDialF is a thin, scriptable bridge between your terminal and a real phone. The control side is clean software over WiFi; the audio side is honest about hardware \u2014 a sound card doing what software isn't allowed to. Together they let a few lines of YAML place a call, hold a conversation, and hand you a clean recording.\n\nIt runs on macOS and Linux, the CLI installs from npm, and the phone app is a sideloadable APK. If you've ever wanted to put a real phone call inside a `for` loop \u2014 that's the idea.\n\n—\n\n## License\n\nDialF is released under the **MIT License**.\n\n**Disclaimer:** This tool is strictly for engineering use only and must not be used for any illegal purposes. The user bears all legal consequences arising from its use.\n<\/div>

A small tool that lets a script place real phone calls, talk, listen, and hang up \u2014 on a real SIM, over a real cellular network.<\/em><\/p>\n

\n

Why we built this<\/h2>\n

AI voice agents are everywhere now \u2014 and they live and die by latency and audio quality.<\/strong> A second of dead air, a stiff robotic voice, or choppy, fluctuating audio is the difference between \u201csounds human\u201d and \u201cobviously a bot.\u201d Yet before every release we were measuring those things by hand<\/em>: dial in, read a script, listen for gaps, do it again on the next build. It didn\u2019t scale, and \u201csounds fine to me\u201d is not a regression test.<\/p>\n

What we actually needed was to automate a real<\/em> phone call. Not a VoIP call. Not a simulator. An actual call on an actual carrier \u2014 the kind that rings a normal phone, goes through the normal network, and behaves exactly like a human dialing. So we could:<\/p>\n