walkai-talkai
entr
Back to home
Troubleshooting

Fix it yourself, step by step.

Every known cause, from cables and radio volume to VOX, left/right channels, sound card levels, agents and licensing. Search by keyword or pick a common question.

Common questions
64 results
  1. 1You need two radios on the same channel: one in your hand, one next to the Mac (the station radio).
  2. 2Station radio SPEAKER output (SP, usually the 3.5 mm plug of a Kenwood-style 2-pin K-plug) → Mac input (USB sound card mic/line in).
  3. 3Mac output (USB sound card headphone out) → station radio MIC input (usually the 2.5 mm plug of the K-plug).
  4. 4In the app: Audio Settings → Input Microphone = the sound card that receives the radio, Output Speaker = the sound card that feeds the radio.
  5. 5A cheap USB sound card with separate mic and headphone jacks is the most reliable option. A ready-made "radio to PC interface cable" (APRS / digital-mode cable) with built-in attenuation is ideal.
#wiring-basics
  1. 1The Mac headphone jack is a combo TRRS (CTIA) jack: it only accepts a microphone through a 4-pole headset plug. A 3-pole (TRS) radio cable will usually give output but no input.
  2. 2Use a TRRS splitter (headset → separate mic and headphone) if you want to use the built-in jack, or better, a USB sound card.
  3. 3Check Audio Settings: the input must show "External Microphone" or the sound card name, not "MacBook Microphone".
#mac-jack
  1. 1The two plugs are probably swapped: radio SP must go to the Mac INPUT, radio MIC must come from the Mac OUTPUT.
  2. 2Make sure the K-plug is pushed all the way in; many radios need a firm push and the plug sits slightly proud of the case.
  3. 3Check that both radios are on the same channel/frequency and the same CTCSS/DCS code (or both off).
  4. 4Use the Test buttons: Audio Settings → microphone card "Test" (records and plays back) and speaker card "Test" (sends a sample announcement).
#swapped-jacks
  1. 1Station radio: VOX ON (sensitivity around 3–5 of 9 to start), squelch 3–5, battery save OFF, dual watch OFF, TOT (transmit time-out) at least 60–120 s, roger beep optional.
  2. 2Handheld: VOX off (you use PTT), same channel and CTCSS/DCS code as the station radio.
  3. 3Volume knob on the station radio sets how loud your voice reaches the Mac; start at about 50–60 %.
  4. 4Some radios disable VOX while an accessory cable is plugged in, or require a separate "VOX on accessory" option; check the radio manual.
#radio-settings
  1. 1Plug the sound card directly into the Mac or into a powered hub; unpowered hubs and long adapters cause dropouts and crackle.
  2. 2Avoid USB-C adapters that also charge the Mac through the same dongle if you hear buzzing.
  3. 3After reconnecting, walkai-talkai rebuilds its audio engine automatically within a few seconds. If listening still does not resume, toggle listening off and on (Station tab or menu bar panel).
#usb-hub
  1. 1Check that listening is on: the Station tab says Listening Active, its spectrum moves while you talk and the menu bar star blinks green.
  2. 2Audio Settings → Input Microphone must be the sound card connected to the station radio SP output.
  3. 3Use the microphone "Test" button: talk on the handheld while it records, then listen to the playback. Silence means the audio never reaches the Mac (cable, jack, radio volume).
  4. 4Turn up the station radio volume knob; if it is near zero the Mac receives almost nothing.
  5. 5macOS System Settings → Sound → Input: select the sound card and raise its input volume; you should see the level meter move when you talk.
  6. 6macOS microphone permission: System Settings → Privacy & Security → Microphone → walkai-talkai must be on.
#not-hearing
  1. 1macOS Mic Mode may be set to Voice Isolation: it treats radio audio as background noise and removes it. Open Control Center (menu bar) → Mic Mode → choose Standard while walkai-talkai is listening.
  2. 2Turn off "Use ambient noise reduction" for the input device if your Mac shows it in Sound settings.
  3. 3Other apps that process the microphone (Krisp, NVIDIA Broadcast-style tools, virtual audio devices) can also suppress radio audio.
#voice-isolation
  1. 1macOS stops the audio engine when devices change (sleep and wake, AirPods/Bluetooth connecting, USB replug). walkai-talkai detects this and rebuilds listening within a few seconds.
  2. 2If it does not recover, toggle listening off and on from the Station tab or the menu bar panel.
  3. 3Bluetooth headphones can become the default input/output; make sure Audio Settings still points to the radio sound card.
#stops-listening
  1. 1Raise the squelch on the station radio so it is silent when nobody transmits; an open squelch sends constant hiss that sounds like speech.
  2. 2Use a CTCSS/DCS code on both radios so other users on the channel do not open your station.
  3. 3Low-frequency rumble and desk thumps are filtered out automatically, but continuous hiss is not; fix it at the radio.
  4. 4Use a USB microphone? Make sure the Input Microphone is the radio sound card, not a room mic that hears everything.
#squelch-noise-rx
  1. 1Anyone on the same frequency can be heard by the station radio. Use an uncommon channel and a CTCSS/DCS code, and keep the station radio power low.
  2. 2Make your agent ask for confirmation before irreversible actions (deleting, pushing, deploying). Announcements and AI replies are also audible to everyone on the frequency.
  3. 3Pause listening when you are not using the station.
#other-users
  1. 1The test recording plays through the current macOS system output (Sound → Output). Raise its volume.
  2. 2If the recording is silent, the input is not receiving audio: check the input device, cable and radio volume (see "I talk on the radio but nothing happens").
  3. 3The microphone test is never sent to Whisper or the AI.
#mic-test-silent
  1. 1Settings → Speech recognition: switch to Whisper Large v3 Turbo (about 1.5 GB download). It is far more accurate, especially for Turkish with English technical terms.
  2. 2Settings → Language must match the language you speak; recognition uses the selected language.
  3. 3Speak 10–15 cm from the handheld mic, at normal volume; shouting distorts FM audio.
  4. 4Set the station radio volume so the microphone Test sounds clear and not clipped.
#wrong-words
  1. 1A command ends after about 1.3 seconds of silence. Avoid long pauses mid-sentence; keep PTT pressed and keep talking.
  2. 2Release PTT only after you finish speaking.
  3. 3If your handheld has battery save or a slow squelch, the start of a transmission may be lost; turn battery save off on both radios.
#cut-sentence
  1. 1Press PTT, wait half a second, then speak. Radios need a moment to key up and open squelch.
  2. 2Turn off battery save on the station radio; in power-save mode it wakes up late and misses the start.
  3. 3Use a CTCSS/DCS code only if needed; some radios add a short delay before opening on a tone.
#first-word-missing
  1. 1Whisper can invent text from noise. walkai-talkai filters common phantom phrases and ignores low-frequency rumble, but continuous hiss can still pass.
  2. 2Raise the squelch, use CTCSS/DCS, and make sure the input is the radio sound card rather than a room microphone.
  3. 3Check Command History: every received command is saved with its audio, so you can hear what triggered it.
#hallucination
  1. 1Recognition uses the language selected in Settings → Language (Turkish or English); it does not auto-detect. Pick the language you speak.
  2. 2Switching the language also starts a fresh AI session in API Mode, so old context does not mix languages.
#wrong-language
  1. 1It is about 1.5 GB; you need a stable connection and at least 2 GB free disk space.
  2. 2Cancel and retry from Settings → Speech recognition. A partial or corrupted file is rejected and the bundled Base model stays active.
  3. 3Whisper Small (about 470 MB) is a good middle ground on slow connections.
#turbo-download
  1. 1Large v3 Turbo is the most accurate but heaviest model. On an M1 with many apps open, try Whisper Small or Base.
  2. 2Long commands take longer; keep commands short and specific.
  3. 3Low Power Mode on a MacBook slows recognition; plug in or turn it off.
#slow-recognition
  1. 1Audio Settings → Output Speaker must be the sound card connected to the station radio MIC input.
  2. 2Output channel: most radio cables use only one side. Default is Right; if nothing goes out, try Left or Stereo.
  3. 3Press the speaker "Test" button and watch the station radio: its TX LED should light. If not, VOX is not opening (see VOX entries) or the cable is in the wrong jack.
  4. 4macOS Sound → Output: select the sound card and set its volume high (80–100 %). The app's own level is applied on top of it.
  5. 5Make sure VOX is turned on in the station radio menu.
#no-transmit
  1. 1The radio VOX needs time to key up. Increase Audio Settings → Advanced Audio Settings → VOX Wake-Up Duration (default 750 ms, range 0–2500 ms) in 250 ms steps.
  2. 2Add a pre-speech hold (0–1500 ms) so the radio is fully transmitting before speech starts.
  3. 3Choose an alert sound (Tactical 3-tone, Motorola chirp…) before speech: it opens VOX and warns the listener.
  4. 4Turn off battery save on the receiving handheld; it may wake up late.
#first-word-cut-tx
  1. 1Raise Audio Settings → Advanced Audio Settings → Post-Speech Tail (0–2000 ms, default 200 ms): the radio keeps transmitting a little longer after the last word.
  2. 2Increase the VOX delay (hang time) in the radio menu so it keeps transmitting a little after speech ends.
  3. 3Every announcement ends with a roger beep; if you never hear it, the radio is dropping the last part.
  4. 4Check the radio TOT (time-out timer): very long announcements are cut when TOT expires. Set it to 60–120 s or more.
#end-cut-tx
  1. 1Raise Audio Settings → Advanced Audio Settings → VOX Hold Tone Level (default 50 %). A quiet 82 Hz tone keeps VOX open during pauses between words.
  2. 2Raise the radio VOX sensitivity one step, or lengthen its VOX delay.
  3. 3If the output is very low (Announcement Output Level near 20 %), VOX may not detect speech reliably; raise it.
#vox-drops
  1. 1Lower Audio Settings → Advanced Audio Settings → Announcement Output Level (20–100 %, default 100 %). A radio MIC input expects a few millivolts; a headphone output is much hotter.
  2. 2Lower the macOS output volume of the sound card to about 50–70 %.
  3. 3Use a cable with an attenuator (10–30 dB) or lower the radio mic gain in its menu if it has one.
  4. 4Choose Output channel Right or Left instead of Stereo if the cable sums both sides.
#distorted-tx
  1. 1Raise Audio Settings → Advanced Audio Settings → Announcement Output Level and the macOS output volume of the sound card.
  2. 2Check the Output channel: with the wrong side selected only a faint crosstalk reaches the radio.
  3. 3Turn up the handheld volume; also try a different pre-speech sound so you can hear when it starts.
#quiet-tx
  1. 1walkai-talkai ignores the input while transmitting and for 1.5 s afterwards, so its own voice is not treated as a command.
  2. 2If a command still appears, the station radio is probably receiving a strong echo or another nearby radio; increase distance between radios and lower power.
#tx-own-echo
  1. 1That is the delivery beep: it confirms the command reached the agent or the AI. Turn it off in Settings → Play a confirmation sound when a command is sent.
#ack-beep
  1. 1The spoken language follows Settings → Language. Turkish uses the Turkish neural voice, English the English one.
  2. 2An agent can override it for a single announcement by sending "lang": "en" or "tr" to /api/reply.
#announce-language
  1. 1Settings → Spoken notice on mode and language change: turn it off if you do not want these notices on the air.
#mode-announcements
  1. 1Station radio volume knob: about 50–60 %. Mac input volume for the sound card: about 50–70 %.
  2. 2Mac output volume for the sound card: 70–100 %. App Announcement Output Level: 100 %, lower it if announcements distort.
  3. 3Radio VOX sensitivity: 3–5 of 9. App VOX wake delay: 750 ms. VOX hold tone: 50 %. Noise gate: 60 %.
  4. 4Change one thing at a time and use the two Test buttons after each change.
#levels-guide
  1. 1Many radio interface cables connect only one channel of the headphone plug to the radio MIC; the other may touch the PTT or speaker line and cause trouble.
  2. 2Start with Right (default). If the radio does not key up during the speaker Test, try Left, then Stereo.
  3. 3The setting is applied digitally inside the app, so the macOS balance slider does not matter; keep it centered anyway.
#left-right
  1. 1Lower the station radio volume knob; this is the most common cause.
  2. 2Lower the Mac input volume of the sound card. walkai-talkai also lowers it step by step automatically if it keeps clipping.
  3. 3Speak at normal volume and not too close to the handheld mic.
#input-clipping
  1. 1Turn up the station radio volume knob and the Mac input volume of the sound card.
  2. 2If your sound card has a line/mic switch, use mic (more gain).
  3. 3The app levels quiet speech before recognition, but a near-silent signal cannot be recovered.
#input-too-low
  1. 1If the radio sound card is the macOS default output, every app plays through the radio. In System Settings → Sound → Output choose your speakers or headphones.
  2. 2walkai-talkai sends announcements to the device selected in Audio Settings regardless of the macOS default.
  3. 3Also set System Settings → Sound → "Play sound effects through" to your speakers.
#system-sounds
  1. 1Open Audio MIDI Setup (Applications → Utilities), select the sound card and set it to 48,000 Hz (or 44,100 Hz), 2 channels, for both input and output.
  2. 2Restart listening after changing the format.
  3. 3Cheap sound cards sometimes misbehave at 96 kHz; avoid it.
#sample-rate
  1. 1Test with walkai-talkai closed. If the radio still keys up, the cause is the hardware path: noise or hum from the sound card output is opening VOX.
  2. 2Unplug the cable from the sound card: if transmitting stops, it is the audio line. Lower the radio VOX sensitivity, lower the macOS output volume, or add a ground loop isolator.
  3. 3Make sure the radio sound card is not the macOS default output (notifications and other apps would key the radio).
  4. 4Lower the app VOX hold tone level; set it to 0 % if your radio holds VOX without it.
  5. 5If the radio keeps transmitting even with the cable unplugged, the radio PTT/VOX itself is stuck: turn the radio off and on.
  6. 6Inside the app a transmission is always force-ended after a timeout, so the app cannot keep the radio keyed forever.
#tx-stuck
  1. 1Classic ground loop: Mac on the charger + USB sound card + radio on its own charger. Try running the Mac on battery; if the hum disappears, add a ground loop isolator (audio isolation transformer) on the line between Mac and radio.
  2. 2Move the radio charger to the same power strip as the Mac.
  3. 3Use short, shielded cables and keep them away from power adapters.
#ground-loop
  1. 1The station radio antenna is too close to the cable or the Mac and its RF gets into the audio line.
  2. 2Move the radio away from the Mac (or use an external antenna), lower the transmit power, and clip ferrite cores on the audio cable near both ends.
#rf-feedback
  1. 1That is the VOX hold tone (82 Hz) that keeps the radio transmitting during pauses. Lower Audio Settings → Advanced Audio Settings → VOX Hold Tone Level, or set it to 0 % if VOX stays open without it.
  2. 2Some radios filter it with CTCSS settings; others pass it through. Find the lowest level that still keeps VOX open.
#hold-tone-audible
  1. 1That is the VOX hold tone playing until the roger beep. Lower Audio Settings → Advanced Audio Settings → Post-Speech Tail (default 200 ms).
  2. 2If the tone continues after the roger beep, it comes from the radio or the cable, not from walkai-talkai: see "The radio stays in transmit".
#tone-after
  1. 1Raise Audio Settings → Advanced Audio Settings → Noise Gate (0–100 %, default 60 %). It silences the background between words.
  2. 2Too high a gate can clip quiet word endings; lower it a little if speech sounds chopped.
#hiss-gaps
  1. 1Check the cable and plug: a loose K-plug or a broken cable crackles when touched.
  2. 2USB power issues cause pops; try another USB port or a powered hub.
  3. 3Wi-Fi/Bluetooth adapters and phones near the cable can cause buzzing bursts; move them away.
#static-bursts
  1. 1Grant Accessibility permission: System Settings → Privacy & Security → Accessibility → walkai-talkai on. A red dot on the menu bar icon means it is missing.
  2. 2After an update macOS sometimes needs the permission re-granted: remove walkai-talkai from the list and add it again.
  3. 3Pick the target again: menu bar panel → Pick target (or right-click the icon → Select Target Input), then click the agent's input box.
  4. 4Some apps block simulated typing in secure fields (password boxes) or when Terminal's "Secure Keyboard Entry" is on; turn that off.
#paste-not-working
  1. 1The target is a point on screen relative to the selected app window. If you moved or resized the window, pick the target again.
  2. 2Keep the target app open (not minimized) and on the same desktop Space.
#wrong-window
  1. 1The agent must know the radio protocol. In the Target Window tab press "Send to Target" to paste the starter prompt into the agent once per session.
  2. 2The prompt tells the agent to POST to http://127.0.0.1:1988/api/reply. Agents that block network or shell access (sandbox, permission prompts) must be allowed to run curl.
  3. 3Old prompts may still contain port 8765; walkai-talkai migrates saved prompts to 1988, but prompts already pasted into an agent conversation must be updated there.
  4. 4Test it yourself: curl -s -X POST http://127.0.0.1:1988/api/reply -H "Content-Type: application/json" -d '{"text":"Test, over."}'
#agent-silent
  1. 1Edit the starter prompt (Target Window tab) and stress: maximum 2–4 short sentences, never read code, end with "over" / "tamam". Send it to the agent again.
  2. 2In API Mode, adjust the starter prompt in API Settings the same way.
#agent-talks-too-much
  1. 1Open API Settings → edit the profile and paste the key again without spaces. Keys for OpenAI, Anthropic, Gemini and DeepSeek are different; each needs its own.
  2. 2Check that the key is active and the account has billing enabled at the provider.
#api-401
  1. 1Your provider account hit its rate or spending limit. Wait a minute, check billing, or switch to another profile.
#api-429
  1. 1The model name is wrong or retired. Edit the profile and choose a model from the refreshed model list.
#api-404
  1. 1Check the internet connection; API Mode needs it (speech recognition and voice do not).
  2. 2Corporate networks and VPNs can block AI providers; try another network.
  3. 3For a custom endpoint, check the URL (it must end with /v1 for OpenAI-compatible servers).
#api-timeout
  1. 1Start Ollama and make sure a model is pulled (for example "ollama pull llama3.1").
  2. 2The endpoint is http://localhost:11434/v1. Pick the exact model name shown by "ollama list".
  3. 3Large local models are slow on small Macs; announcements will wait for the full answer.
#ollama
  1. 1Each profile and model has its own sessions. Switching profile/model or language starts or resumes a different session.
  2. 2Pick the session in API Settings → Conversation session, or keep context enabled.
#api-context
  1. 1walkai-talkai must be running. The API listens only on 127.0.0.1 (not on your network).
  2. 2Another app may be using port 1988: run "lsof -nP -iTCP:1988 -sTCP:LISTEN" in Terminal to see which.
  3. 3Old prompts or scripts may still use 8765; update them to 1988.
#localapi-refused
  1. 1The license is not active. Activate it in About → License; announcements through the API require an active license.
#localapi-403
  1. 1Send a JSON body like {"text": "..."} with Content-Type: application/json; charset=utf-8.
  2. 2Escape quotes inside the text, and make sure the shell does not break UTF-8 characters (use single quotes around the JSON in zsh/bash).
#localapi-json
  1. 1Copy the key exactly as in the email (WALKAI-XXXX-XXXX-XXXX). It is not case sensitive.
  2. 2Activation needs internet once. Check your connection and firewall.
  3. 3A license works on one Mac at a time. If it is active on another Mac, remove it there (About → License → Remove from This Mac) and activate again.
  4. 4If the old Mac is gone, contact support with your purchase email to reset the activation (see walkai-talkai.com/license).
  5. 5Need the app again? Download it with your key at walkai-talkai.com/license.
#license-activate
  1. 1Without the app: go to walkai-talkai.com/license, enter your purchase email and we email the key together with a download link.
  2. 2In the app: activation window or About → License → "I lost my key", then enter your purchase email.
  3. 3Check spam. Requests are rate limited; wait a few minutes before trying again.
#license-lost
  1. 1The license is re-checked online from time to time; between checks the app works offline for up to 14 days. About → License shows the last check and the days left.
  2. 2Connect to the internet and open the app; the check happens automatically.
#license-offline
  1. 1On the old Mac: About → License → Remove from This Mac. On the new Mac: enter the same key.
#license-move
  1. 1System Settings → Privacy & Security → Microphone → turn walkai-talkai on, then restart listening.
  2. 2If walkai-talkai is not in the list, quit and reopen it so macOS asks again.
#mic-permission
  1. 1About → Check for Updates. Updates are signed and notarized and delivered in the app.
  2. 2If no update appears you already have the latest version; the About tab shows your version.
#updates
  1. 1Update to the latest version (About → Check for Updates); a crash on quit was fixed.
  2. 2If it keeps happening, send the report text to support (the "Report…" button in the macOS dialog shows it).
#crash-report
  1. 1Listening is on by default so the station is ready. Pause it from the Station tab or the menu bar panel when you do not need it.
  2. 2If the input is a room microphone, sounds at startup can be treated as speech; use the radio sound card as input.
#auto-start

Still stuck? Email support with what you tried and your macOS version. [email protected]

Guide for AI agents

If you are an AI agent helping a walkai-talkai user, use this page as your knowledge base:

  1. 1.Read the station state first: curl -s http://127.0.0.1:1988/api/status (listening, operation_mode, language, input_device, output_device, last_command, ai_provider, ai_model).
  2. 2.Match the user's symptom to an entry below (each has an id, for example #tx-stuck) and walk through its steps in order; the most likely cause is first.
  3. 3.Only suggest settings the user can change in the app, macOS or the radio. Setting names and ranges on this page match the app.
  4. 4.Do not send test announcements (/api/reply) without asking: they are transmitted over a real radio frequency.
  5. 5.The full guide as plain text for tools: /troubleshooting.txt
Plain-text version for agents → /troubleshooting.txt