Author image Doug Haber
and 1 contributors


GQRX::Remote - Control Gqrx using the Remote Control protocol


    use GQRX::Remote;

    # Initialize a $remote and connect to the local server
    my $remote = GQRX::Remote->new();


    # Set up some options
    $remote->set_frequency(44000000);  # 44,000 kHz

    # Retrieve the signal strength
    my $strength = $remote->get_signal_strength();


The GQRX::Remote module provides a Perl interface to the remote control protocol of the Gqrx software defined radio program. Using this, programs can communicate with a Gqrx instance over a socket connection.


To begin using this module, create a remote object:

    my $remote = GQRX::Remote->new();

This object provides the interface for using and managing a connection to Gqrx.

    my $remote = GQRX::Remote->new(exit_on_error => 1);

When exit_on_error is enabled, any errors encountered are considered fatal and will cause a die to be executed. This is useful when writing simple scripts, where errors would cause the execution to fail anyway. It is for convenience and can save a programmer a little time. While this might make sense for some scripts, applications generally should not use it, and instead perform proper error checking and handling.


If the module is initialized with the exit_on_error option, all errors will results in a die() call with the error message. Otherwise, calls that fail will return a value of undef when a failure occurs.

In these situations, the error message is retrievable by calling $remote->error(). This returns a string containing the error message.

    # Example handling of an error
    if (! defined $remote->get_signal_strength()) {
        print "get_signal_strength() failed with error: " . $remote->error();


This module connects to a Gqrx instance at a defined IP address and port. By default, this is the localhost ( and port 7356.

    # Connect to

    # If the server isn't local and on the default port, these
    # may be overridden
    $remote->connect(host => '', port => 4242);

After successfully connecting, a 1 will be returned. In the case of a failure, a 0 will be returned, and an error will be set. If exit_on_error is enabled, failures will exit, but otherwise they should be captured and handled.

    if (! $remote->connect()) {
       # Connection failed



    # To get the frequency:
    $frequency = $remote->get_frequency();

    # To set the frequency:
    $remote->set_frequency(44000000); # 44,000 kHz

All frequency values are in hertz.

On success the set_frequency() call returns 1. On failure, either call will return undef.


    # To get the demodulator_mode:
    $demodulator_mode = $remote->get_demodulator_mode();

    # To set the demodulator_mode:

Any demodulator mode supported by Gqrx should work. At the current time this includes: AM, FM, WFM, WFM_ST, WFM_ST_OIRT, LSB, USB, CW, CWL, CWU.

On success the set_demodulator_mode() call returns 1. On failure, either call will return undef.


    # Retrieve the signal strength

On success, this returns the signal strength. On failure, it will return undef.


    # To get the squelch_threshold:
    $squelch_threshold = $remote->get_squelch_threshold();

    # To set the squelch_threshold:

On success the set_squelch_threshold() call returns 1. On failure, either call will return undef.


    # Start recording

    # Stop recording

These calls can be used to automatically recording of audio in Gqrx. On success they return 1, and on failure undef.

RECORDER STATUS (experimental)


The API documentation lists the protocol for getting and setting recorder status. As of Gqrx 2.5.3 these requests always fail. The implementation has been included to provide for complete support of the documented protocol.

Recording audio files can be still be achieved via the start_recording() and stop_recording() calls.

On success set_recorder_status() returns 1. On failure, either call will return undef.


* GQRX::Remote on GitHub:

* Example script for collecting signal strength data: (included in distribution)

* Gqrx:

* Gqrx remote control protocol documentation:


Original author & current maintainer: Doug Haber <>


Either the Perl Artistic Licence or the GPL


Copyright (c) 2016 Douglas Haber

All rights reserved. This is free software. You may distribute under the terms of either the GNU General Public License or the Artistic License.