Package: pyaudible
PyAudible 1.1.0A Python library for sending and receiving data using audible sound. PyAudible includes a transmitter and a receiver module that could be implemented on multiple devices, enables the transmission of small amounts of data between separated systems in the vicinity.The library implements a Multi-channel Carrier Modulation protocol, allows a configurable transmitting speed between 5 - 20 bytes/sec. It usesCyclic Redundancy Check (CRC)to ensure reliable data delivery.The transmitter and the receiver provide simplified Python interface that could be easily integrated in various other projects, possible scenarios includes:Smart Home Appliances (IoT)Data BroadcastingDevice PairingElectronic Key SharingThis README file provides a walkthrough of the project, include a quickstart, brief documentation and evaluation.Other docs can be found at:Full DocumentationProtocol DetailsTest & EvaluationsProject RoadmapQuickstartTested on Python 3.8RequirementsPython3.6+PyAudio0.2.11+ (speaker access required for the transmitter, microphone access required for the receiver)Numpy1.18.5+InstallationWith required dependencies installed, usepip install pyaudibleto download and install PyAudible.To validate the installation, run the following code and it should print the version of the transmitter, receiver, PyAudio and PortAudio to the console.from pyaudible import transmitter, receiver
transmitter.print_transmitter_version()
receiver.print_receiver_version()After the installation, keep following the examples provided below or refer to the fulldocumentationfor more information.Examples and DemosThe following examples will demonstrate the basic transmission protocol of PyAudible. More examples could be find in the fulldocumentation.Example: Modulate and Transmit DataIn this example we converted a message to electrical signals and generated the modulated audio file."""PyAudible Example: Modulate and Transmit Data"""frompyaudibleimporttransmitter# instantiate the transmittertx=transmitter.Transmitter(speed='fast',volume=1.0)# define the message to be transmittedmessage='Hello World!'# define the filenamefilename='transmitter_sample.wav'# modulate the message and store the modulated signal to an audio filetx.modulate_to_file(message,filename)Example: Receive and Demodulate Data (Blocking Mode)In this example we set up a PyAudible Receiver and kept it on standby for 30 seconds. If the transmitted signal was played during the standby time, it would capture and convert the signal back to text."""PyAudible Example: Receive and Demodulate Data (Blocking Mode)"""frompyaudibleimportreceiver# instantiate the receiverrx=receiver.Receiver(sensitivity='medium',speed='auto')# active the receiver for 30 secondsretrieved_data=rx.read_block(30)Protocol OverviewThis section briefly demonstrated the transmission protocol, however, a full detailed explanation could be found inProtocol Details.Figure 1: Multi-channel Carrier ModulationThe protocol utilises aFrequency-Shift Keying (FSK)technique to modulate the raw data into an eight-channel carrier signalChannel_01-Channel_08. Each carrier channel transmits data by switching the frequency within a range of 16 candidate frequenciesFC(0)-FC(15)(Shown inFigure 1). And each candidate frequency represents a 4-bit chunk (0000,0001...1111). Therefore, 8 x 16 = 128 candidate frequencies are equally spaced between1238 Hzto6965 Hz, divided bydF = 43.0 kHz. The original data is converted into binary representations, and then it is encapsulated into packets of 8, 16 or 32 bits per unit time (depending on the transmission rate), then transmitted via 2, 4 or 8 channels.To handle the transmission signal, the receiver maintains seven Status Flags to signifying the status of the current connection, shown inFigure 2below.Figure 2: Receiver Handling BehavioursThe beginning and ending bits of the transmission sequences are the Activating and Terminating Sound Mark. Each part of the sound mark contains essential session descriptors to establish and terminate the connection, shown inFigure 3below. These descriptors also maintain important functionalities include flow control and noise resistance mechanism.Figure 3: Sound Marks StructureDocumentationFull documentation provided inDocumentation.Alternatively, the documentation can be generated and viewed via__doc__, for exampleprint(receiver.Receiver.read_block.__doc__).Test and Evaluation (Overview)Full experimentation designs and the evaluation results provided inTest & Evaluationdocument.The evaluations of the system were conducted along with the development.Phase I Evaluationassessed the reliability of the noise resistance mechanism in different noise conditions, and verified that the system can achieve at least 90% reliability with a transmission rate at 20 bytes/sec.Phase II Evaluationgave a statistical analysis on the reliability with respect to the transmission speed and the signal to noise ratio. The following Speed-Rate-Reliability Lookup Table is taken from theresults of Phase II Evaluation, which could help users to decide transmission settings based on noise situations:Transmission SpeedTransmission Success RateReliabilitySignal to Noise Ratio = 1.25 bytes/sec (slow)0.200.8010 bytes/sec (medium)0.110.5520 bytes/sec (fast)0.070.38Signal to Noise Ratio = 1.55 bytes/sec (slow)0.720.9010 bytes/sec (medium)0.540.8020 bytes/sec (fast)0.470.77Signal to Noise Ratio = 25 bytes/sec (slow)0.991.0010 bytes/sec (medium)0.730.9720 bytes/sec (fast)0.660.90Signal to Noise Ratio = 2.55 bytes/sec (slow)0.991.0010 bytes/sec (medium)0.951.0020 bytes/sec (fast)0.900.97Speed - Rate - Reliability Lookup TableLatest Updates04.01.21 V1.1.0Compatible to any audio backends as long as it provides buffered audio analysis.Full update history provided inUpdates.AcknowledgmentThis project is carry out in comply with the guidelines of COMP390 module, as a key element of the Honours Year Project.LicenseMIT