README.txt

APT encoder
===========

1. Synopsis

   apt-encoder reads image files and turns them into sound data modulated as APT
   signals. APT is a way to send images as audio, and it is used by NOAA weather
   satellites. It is a simple format that a lot of people recognize by sound,
   and decoders for it are easily available. This makes it a good candidate for
   simple radio faxing.

2. License

   This program is free software: you can redistribute it and/or modify it under
   the terms of the GNU Affero General Public License as published by the Free
   Software Foundation, either version 3 of the License, or (at your option) any
   later version.
   
   This program is distributed in the hope that it will be useful, but WITHOUT
   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
   FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more
   details.
   
   You should have received a copy of the GNU Affero General Public License
   along with this program.  If not, see <https://www.gnu.org/licenses/>.

2. User manual


2.1. Building the software

   In order to build the project, run `make`. It will produce a binary called
   'apt-encode'. You will need to have Make and a C++ compiler on your system.

2.2. Picture format

   The program needs pictures encoded in the PGM format [1]. You can use an
   image editor, such as GIMP, in order to create these files. The format needed
   by the program is P2, also known as the 'Text' encoding of PGM.

   The images will need to have a width of 909 pixels, and they can have any
   height. The program can handle images of different heights. If two images
   with different heights are encoded, the shorter image will be padded with
   black pixels.

2.3. Configuration parameters

   The program has a few knobs that can be tweaked. These are located in the
   "Constants and config" section of the C++ file. If you want the signal to be
   understood by existing decoders, you should only change the OVERSAMPLE
   option.

   CARRIER: This option determines the carrier frequency of the output. It is
   defined to be 2400 Hz by the APT specification.

   BAUD: Determines the speed of the transmission. The APT specification defines
   this to be 4160.

   OVERSAMPLE: How many audio samples to output for each word. The output sample
   rate is BAUD * OVERSAMPLE.

   SYNCA and SYNCB: Sync words that appear before image A and image B
   respectively.

2.4. Usage examples

2.4.1. Encoding the same image for both sections

   In order to provide some data redundancy, you can transmit the same picture
   for both images of the transmission. Just pass the same file to the program
   twice.

   ./apt-encode ~/image1.pgm ~/image2.pgm

2.4.2. Playing the output from the computer

   You can play the output signal from the computer sound card / speakers.

   ./apt-encode ~/image1.pgm ~/image2.pgm | aplay -r 8320

   Replace 8320 with the actual sample rate based on the oversample value.

2.4.3. Creating WAV files

   ./apt-encode ~/image1.pgm ~/image2.pgm > encode.raw
   sox -t raw -b 8 -e unsigned -c 1 -r 8320 encode.raw -r 11025 ~/apt.wav

   This creates a WAV file with a sample rate of 11025.

3. Links and references

   [1]: https://en.wikipedia.org/wiki/Netpbm#PGM_example