A Human Radio Interface for Opulent Voice is ready for you to try out at https://github.com/OpenResearchInstitute/interlocutor
Overview
Interlocutor is the human-radio interface component of the Open Research Institute’s Opulent Voice digital communication system. Think of it as the “radio console” that transforms your computing device (such as Raspberry Pi or a laptop) into a sophisticated digital voice and data terminal. While traditional amateur radio digital modes often sacrifice audio quality for bandwidth efficiency, Interlocutor enables very high-quality voice communications with seamless integration of keyboard chat, file transfer, and system control messages.
What Does Interlocutor Do?
Interlocutor provides high-quality digital voice communication using the high-bitrate open source Opus voice encoder. It enables keyboard chat that integrates seamlessly with voice, handles file transfer and system control messages, and offers both command-line and web-based interfaces. Interlocutor manages audio devices with sophisticated conflict resolution and implements priority-based message queuing (voice always wins)
It acts as the bridge between human operators and radio equipment. It processes voice, text, and data into properly formatted frames that can be sent to any Opulent Voice-compatible modem via Ethernet, enabling remote operation and modular system design.
On first run, you’ll be prompted to:
1. Select audio input device where you choose your microphone.
2. Test audio input where you speak to verify microphone works.
3. Select audio output device where you choose your speakers/headphones
4. Test audio output where you listen for test tone.
Where to Send Your Frames?
After Interlocutor does all the work required to gather your voice and text input and create Opulent Voice Protocol frames, those frames are then sent to a modem or other program that can make use of them. How does this work? If frames are sent to a modem then it turns the frames into a modulated signal. This signal is then sent out over the air. The current implemented target modem is the PLUTO SDR from Analog Devices.
Or, the frames can go to a computer or conference server over the Internet. In other words, frames can be sent to another computer, a modem for radio transmission, a conference server (repeater) receiver, and more. If it has an IP address, and if it understands what to do with the frames, then you are ready to communicate.
The Basics of Running Interlocutor
See the online manual for detailed installation instructions.
# Launch with web interface
python3 interlocutor.py YOUR_CALLSIGN --web-interface
# Launch with a specific config file
python3 interlocutor.py YOUR_CALLSIGN -c myconfig.yaml --web-interface
You’ll need to configure network targets to tell Interlocutor where your Opulent Voice data frames need to be sent. Modify the network target configuration through the web interface in the Target IP Address box or use the command-line argument like this:-i <IP address>
as needed.
The web interface is available at http://localhost:8000 on the device running interlocutor.py.
Interlocutor features a modern glassmorphism-styled web interface for operation and complete system configuration. All configuration items are available at the command line or in the web interface.
The purpose of the Configuration System is to create, validate, and save one or more configuration files so that an operator can start the radio in a fully defined state.
Operational Modes
First, let’s talk about the command line interface (CLI) mode. This offers traditional terminal-based operation with full keyboard chat capabilities.
The simplest way to invoke this mode is by typing:
python3 interlocutor.py YOUR_CALLSIGN
In CLI mode, real-time voice transmission is done with a hardware PTT button. There is a keyboard chat interface. Voice has priority, with control messages second highest priority, and keyboard chat third. Debug output and system status are shown as text on the screen.
Second, let’s explore the web interface mode. The web interface is a modern browser-based interface with visual controls.
It is invoked by adding the –web-interface argument to program start.python3 interlocutor.py YOUR_CALLSIGN --web-interface
We find a detailed configuration management in Configuration tab, live status indicators, and real-time voice transmission with PTT control available in three different ways. First, as a hardware switch on designated GPIOs. Second, as a clickable button in the web interface. Third, the space bar when the message entry box does not have focus. Web interface has keyboard chat and shows system log, notifications for important events, debug output, and system status. Sent and received audio can be replayed from the message history window.
Dual-Mode Operation
Both interfaces can run simultaneously, providing flexibility for different operational scenarios or preferences. There are instant updates between command line and web interfaces via WebSocket communication.
Protocol and Network Configuration
Interlocutor implements the Opulent Voice protocol with sophisticated frame management. Here are the frame types and priorities.
1. VOICE (Priority 1): Opus-encoded audio, immediate transmission
2. CONTROL (Priority 2): PTT state changes, high priority queue, A5 messages
3. TEXT (Priority 3): Keyboard chat, normal priority queue
4. DATA (Priority 4): File transfers, low priority queue
External Network Ports:
57372: Network Transmitter port (configurable, connects to radio hardware, computer, or repeater). This is the only port you have to configure.
Internal Protocol Ports:
57373: Audio frames
57374: Text frames
57375: Control frames
These ports tell the receiver what kind of information it’s receiving. These ports are in the UDP header in each Opulent Voice frame. The protocol is extendable. Future data types get the next port available.
All frames follow the Opulent Voice protocol format.
Opulent Voice Header: 12 bytes (sync word + station ID + type + sequence + length + reserved)
Payload: 122 bytes of data loaded up in 40 ms frames
Encoding: COBS (Consistent Overhead Byte Stuffing) framing
Transport: UDP over IP with RTP headers for audio, UDP over IP for control, text, and data
Network Integration
# Basic operation (connects to default target with default values)
python3 interlocutor.py YOUR_CALLSIGN
# Specify target IP and port
python3 interlocutor.py YOUR_CALLSIGN --target-ip 192.168.1.100 --target-port 57372
# Load specific configuration file
python3 interlocutor.py YOUR_CALLSIGN -c mystation.yaml
Audio System Operation
Push-to-Talk (PTT) Operation:
GPIO Button: Physical button connected to Raspberry Pi GPIO
Web PTT: Additional click/touch controls in web interface. There’s a PTT button and the space bar activates PTT when the message entry box is not highlighted (does not have focus).
Audio Processing Pipeline:
1. Microphone input to PyAudio capture
2. Audio validation
3. Opus encoding (40ms frames, 16,000 bps bitrate)
4. Hardware audio callback
5. RTP header addition
6. UDP header addition
7. IP header addition
8. COBS encoding
9. Opulent Voice header addition
10. Network transmission
Chat Integration
Voice transmission has absolute priority. Text messages typed during PTT are buffered. Buffered messages transmit immediately when PTT releases. Control messages maintain high priority for system functions
Chat Modes:
Voice + Chat: Normal operation with seamless integration. Operators can choose voice or text as appropriate. This is the default mode.
Chat Only Mode: Keyboard-to-keyboard communication (similar to RTTY). This is set up with a command line argument--chat-only
Automatic Reconnection System
Interlocutor implements intelligent reconnection logic for the web interface.
Reconnection Timing is as follows.
1. First retry: 1 second delay
2. Subsequent retries: Exponential backoff (1.5x increase)
3. Maximum delay: 30 seconds
4. Maximum attempts: 10 attempts
5. Total auto-retry time: 2-3 minutes
A manual retry button appears after auto-retry exhaustion.
Documentation Resources
Project repository: https://github.com/OpenResearchInstitute/interlocutor
Open Research Institute: https://www.openresearch.institute/getting-started
GitHub Issues for bug reports
Code contributions welcome via GitHub pull requests and filing issues. Documentation improvements welcome and encouraged. Testing and feedback valuable for development. Hardware testing on different platforms welcome and encouraged!
The system is actively developed open-source software, and features may evolve. Check the project repository for the latest updates and documentation.