| Name | gg-transfer JSON |
| Version |
0.2.6
JSON |
| download |
| home_page | None |
| Summary | FSK text/file transfer utility |
| upload_time | 2024-08-29 10:15:07 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# gg-transfer
---
## Tool to send/receive text/binary file over audio via FSK modulation
This tool is intended to send/receive short text messages or whole binary files over audio.
It uses `ggwave` library ([https://github.com/ggerganov/ggwave](https://github.com/ggerganov/ggwave)) to encode text messages or binary files, send
them over the audio interface, or decode them from the microphone.
It can be used - and its main purpose is - to send data through radio transceivers. See https://github.com/matteotenca/fm-transfer
This is a shell front-end which implements the sending/receiving of bare text or whole binary files, which are encoded in Base64.
In `--file-transfer` mode, the file is opened and read all at once, then is encoded in Base64, and a header in JSON
with some info about the file itself is sent. The Base64 encoded string is split into 132 bytes/long chunks, and a
CRC32 is added at the beginning of the block to reach the maximum block size allowed by `ggwave`, 140 bytes.
The CRCs are inserted shifted by one block to be sure the blocks arrive in the right order. At last, the checksum of the whole file
is checked against the one received in the header.
The standard behaviour is to play/record audio to/from the default audio devices.
There are nine different protocols to send data:
```
0 = Normal (11,17 Bytes/s - 1875 Hz to 6375 Hz)
1 = Fast (16,76 Bytes/s - 1875 Hz to 6375 Hz)
2 = Fastest (33,52 Bytes/s 1875 Hz to 6375 Hz)
3 = [U] Normal (11,17 Bytes/s - 15000 Hz to 19500 Hz)
4 = [U] Fast (16,76 Bytes/s - 15000 Hz to 19500 Hz)
5 = [U] Fastest (33,52 Bytes/s - 15000 Hz to 19500 Hz)
6 = [DT] Normal (3,72 Bytes/s - 1125 Hz to 2625 Hz)
7 = [DT] Fast (5,59 Bytes/s - 1125 Hz to 2625 Hz)
8 = [DT] Fastest (11,17 Bytes/s - 1125 Hz to 2625 Hz)
```
### Installation
```bash
$> pip install gg-transfer
```
##### Warning:
On PyPi, `ggwave-wheels` is now required, altough it provides the very same functions of the original `ggwave` package.
This is due to some glitches in the original `ggwave` install process under python `>=3.11`. `ggwave-wheels` provides
some pre-compiled wheels for `linux` and `windows` `x64` platforms.
### Test installation
```bash
$> git clone https://github.com/matteotenca/gg-transfer.git
$> cd gg-transfer
$> pip install --user -e .
```
### Examples:
```
usage: gg-transfer send [-h] [-i <inputfile>] [-p {0,1,2,3,4,5,6,7,8}] [-f]
Command line utility to send/receive files/strings via ggwave library (FSK).
options:
-h, --help show this help message and exit
-i <inputfile>, --input <inputfile>
input file (use '-' for stdin).
-p {0,1,2,3,4,5,6,7,8}, --protocol {0,1,2,3,4,5,6,7,8}
protocol, 0 to 8 (defaults to 0)
0 = Normal (11,17 Bytes/s - 1875 Hz to 6375 Hz)
1 = Fast (16,76 Bytes/s - 1875 Hz to 6375 Hz)
2 = Fastest (33,52 Bytes/s 1875 Hz to 6375 Hz)
3 = [U] Normal (11,17 Bytes/s - 15000 Hz to 19500 Hz)
4 = [U] Fast (16,76 Bytes/s - 15000 Hz to 19500 Hz)
5 = [U] Fastest (33,52 Bytes/s - 15000 Hz to 19500 Hz)
6 = [DT] Normal (3,72 Bytes/s - 1125 Hz to 2625 Hz)
7 = [DT] Fast (5,59 Bytes/s - 1125 Hz to 2625 Hz)
8 = [DT] Fastest (11,17 Bytes/s - 1125 Hz to 2625 Hz)
-f, --file-transfer encode data in Base64 and use file transfer mode.
```
```
usage: gg-transfer receive [-h] [-o <outputfile>] [-f] [-w]
Command line utility to send/receive files/strings via ggwave library (FSK).
options:
-h, --help show this help message and exit
-o <outputfile>, --output <outputfile>
output file (use '-' for stdout).
-f, --file-transfer decode data from Base64 and use file transfer mode.
-w, --overwrite overwrite output file if it exists.
```
#### A simple string:
###### Sender side
```bash
$> echo "Hello world" | gg-transfer send --protocol 2
Sending data, length: 16
Piece 1/1 16 B
Time taken to encode waveform: 1.2990546226501465
Speed (payload only): 12.316649139324932 B/s
$>
```
###### Receiver side
```bash
$> gg-transfer receive
Listening ... Press Ctrl+C to stop
Hello world
[...]
```
#### A binary file:
###### Sender side
```bash
$> gg-transfer send --protocol 2 --input somefile.bin --file-transfer
Sending header, length: 71
Pieces: 2
Sending data, length: 176
Piece 2/2 176 B
Time taken to encode waveform: 6.816471338272095
Speed (size of encoded payload + CRC): 23.47255523567687 B/s
Speed (payload only): 17.311009486311693 B/s
$>
```
###### Receiver side
```bash
$> gg-transfer.exe receive --output /tmp/out.bin --file-transfer
Listening ... Press Ctrl+C to stop
Got header - Filename: .gitignore, Size: 118, CRC32: bec88992, Total pieces: 2
Piece 2/2 176 B
File received, CRC correct!
```
#### From code:
###### Sender side
```python
import ggtransfer
s = ggtransfer.Sender(protocol=2)
s.send("1234567890" * 15)
```
###### Receiver side
```python
import ggtransfer
r = ggtransfer.Receiver(file_transfer=False)
rr = r.receive()
```
### Contacts
You can contact me from my GitHub page at [https://github.com/matteotenca/gg-transfer](https://github.com/matteotenca/gg-transfer)
Raw data
{
"_id": null,
"home_page": null,
"name": "gg-transfer",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Matteo Tenca <matteo.tenca@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ff/e9/84ca76a0ea13a47b8c8d8c61c70e7b1f47e4fb42448c9aec683053dc4919/gg_transfer-0.2.6.tar.gz",
"platform": null,
"description": "# gg-transfer\r\n\r\n---\r\n\r\n\r\n\r\n\r\n\r\n## Tool to send/receive text/binary file over audio via FSK modulation\r\n\r\nThis tool is intended to send/receive short text messages or whole binary files over audio. \r\nIt uses `ggwave` library ([https://github.com/ggerganov/ggwave](https://github.com/ggerganov/ggwave)) to encode text messages or binary files, send\r\nthem over the audio interface, or decode them from the microphone.\r\n\r\nIt can be used - and its main purpose is - to send data through radio transceivers. See https://github.com/matteotenca/fm-transfer \r\n\r\nThis is a shell front-end which implements the sending/receiving of bare text or whole binary files, which are encoded in Base64.\r\n\r\nIn `--file-transfer` mode, the file is opened and read all at once, then is encoded in Base64, and a header in JSON\r\nwith some info about the file itself is sent. The Base64 encoded string is split into 132 bytes/long chunks, and a \r\nCRC32 is added at the beginning of the block to reach the maximum block size allowed by `ggwave`, 140 bytes.\r\nThe CRCs are inserted shifted by one block to be sure the blocks arrive in the right order. At last, the checksum of the whole file\r\nis checked against the one received in the header.\r\n\r\nThe standard behaviour is to play/record audio to/from the default audio devices. \r\n\r\nThere are nine different protocols to send data:\r\n```\r\n 0 = Normal (11,17 Bytes/s - 1875 Hz to 6375 Hz)\r\n 1 = Fast (16,76 Bytes/s - 1875 Hz to 6375 Hz)\r\n 2 = Fastest (33,52 Bytes/s 1875 Hz to 6375 Hz)\r\n 3 = [U] Normal (11,17 Bytes/s - 15000 Hz to 19500 Hz)\r\n 4 = [U] Fast (16,76 Bytes/s - 15000 Hz to 19500 Hz)\r\n 5 = [U] Fastest (33,52 Bytes/s - 15000 Hz to 19500 Hz)\r\n 6 = [DT] Normal (3,72 Bytes/s - 1125 Hz to 2625 Hz)\r\n 7 = [DT] Fast (5,59 Bytes/s - 1125 Hz to 2625 Hz)\r\n 8 = [DT] Fastest (11,17 Bytes/s - 1125 Hz to 2625 Hz)\r\n```\r\n\r\n### Installation\r\n\r\n```bash\r\n$> pip install gg-transfer\r\n```\r\n\r\n##### Warning:\r\nOn PyPi, `ggwave-wheels` is now required, altough it provides the very same functions of the original `ggwave` package.\r\nThis is due to some glitches in the original `ggwave` install process under python `>=3.11`. `ggwave-wheels` provides \r\nsome pre-compiled wheels for `linux` and `windows` `x64` platforms.\r\n\r\n### Test installation\r\n\r\n```bash\r\n$> git clone https://github.com/matteotenca/gg-transfer.git\r\n$> cd gg-transfer\r\n$> pip install --user -e .\r\n```\r\n\r\n### Examples:\r\n\r\n```\r\nusage: gg-transfer send [-h] [-i <inputfile>] [-p {0,1,2,3,4,5,6,7,8}] [-f]\r\n\r\nCommand line utility to send/receive files/strings via ggwave library (FSK).\r\n\r\noptions:\r\n -h, --help show this help message and exit\r\n -i <inputfile>, --input <inputfile>\r\n input file (use '-' for stdin).\r\n -p {0,1,2,3,4,5,6,7,8}, --protocol {0,1,2,3,4,5,6,7,8}\r\n protocol, 0 to 8 (defaults to 0)\r\n 0 = Normal (11,17 Bytes/s - 1875 Hz to 6375 Hz)\r\n 1 = Fast (16,76 Bytes/s - 1875 Hz to 6375 Hz)\r\n 2 = Fastest (33,52 Bytes/s 1875 Hz to 6375 Hz)\r\n 3 = [U] Normal (11,17 Bytes/s - 15000 Hz to 19500 Hz)\r\n 4 = [U] Fast (16,76 Bytes/s - 15000 Hz to 19500 Hz)\r\n 5 = [U] Fastest (33,52 Bytes/s - 15000 Hz to 19500 Hz)\r\n 6 = [DT] Normal (3,72 Bytes/s - 1125 Hz to 2625 Hz)\r\n 7 = [DT] Fast (5,59 Bytes/s - 1125 Hz to 2625 Hz)\r\n 8 = [DT] Fastest (11,17 Bytes/s - 1125 Hz to 2625 Hz)\r\n -f, --file-transfer encode data in Base64 and use file transfer mode.\r\n```\r\n\r\n```\r\nusage: gg-transfer receive [-h] [-o <outputfile>] [-f] [-w]\r\n\r\nCommand line utility to send/receive files/strings via ggwave library (FSK).\r\n\r\noptions:\r\n -h, --help show this help message and exit\r\n -o <outputfile>, --output <outputfile>\r\n output file (use '-' for stdout).\r\n -f, --file-transfer decode data from Base64 and use file transfer mode.\r\n -w, --overwrite overwrite output file if it exists.\r\n```\r\n#### A simple string:\r\n\r\n###### Sender side\r\n```bash\r\n$> echo \"Hello world\" | gg-transfer send --protocol 2\r\nSending data, length: 16\r\nPiece 1/1 16 B\r\nTime taken to encode waveform: 1.2990546226501465\r\nSpeed (payload only): 12.316649139324932 B/s\r\n$>\r\n```\r\n###### Receiver side\r\n```bash\r\n$> gg-transfer receive\r\nListening ... Press Ctrl+C to stop\r\nHello world\r\n[...]\r\n```\r\n\r\n#### A binary file:\r\n\r\n###### Sender side\r\n```bash\r\n$> gg-transfer send --protocol 2 --input somefile.bin --file-transfer\r\nSending header, length: 71\r\nPieces: 2\r\nSending data, length: 176\r\nPiece 2/2 176 B\r\nTime taken to encode waveform: 6.816471338272095\r\nSpeed (size of encoded payload + CRC): 23.47255523567687 B/s\r\nSpeed (payload only): 17.311009486311693 B/s\r\n$>\r\n```\r\n###### Receiver side\r\n```bash\r\n$> gg-transfer.exe receive --output /tmp/out.bin --file-transfer\r\nListening ... Press Ctrl+C to stop\r\nGot header - Filename: .gitignore, Size: 118, CRC32: bec88992, Total pieces: 2\r\nPiece 2/2 176 B\r\nFile received, CRC correct!\r\n```\r\n\r\n#### From code:\r\n\r\n###### Sender side\r\n```python\r\nimport ggtransfer\r\n\r\ns = ggtransfer.Sender(protocol=2)\r\ns.send(\"1234567890\" * 15)\r\n```\r\n\r\n###### Receiver side\r\n```python\r\nimport ggtransfer\r\n\r\nr = ggtransfer.Receiver(file_transfer=False)\r\nrr = r.receive()\r\n```\r\n\r\n### Contacts\r\n\r\nYou can contact me from my GitHub page at [https://github.com/matteotenca/gg-transfer](https://github.com/matteotenca/gg-transfer)\r\n",
"bugtrack_url": null,
"license": null,
"summary": "FSK text/file transfer utility",
"version": "0.2.6",
"project_urls": {
"Homepage": "https://github.com/matteotenca/gg-transfer"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "03994a277831f2ee3bc53836dac55a63ecc5d96b0abbcf8c9dd9e19ac0bda5d3",
"md5": "10c3e8a5c2a9b665e9256cce37a1adf6",
"sha256": "7197ede8959e09c37a07af21adb9718ab95e76998bcea1e367dbf1295c298478"
},
"downloads": -1,
"filename": "gg_transfer-0.2.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "10c3e8a5c2a9b665e9256cce37a1adf6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 24284,
"upload_time": "2024-08-29T10:15:06",
"upload_time_iso_8601": "2024-08-29T10:15:06.574960Z",
"url": "https://files.pythonhosted.org/packages/03/99/4a277831f2ee3bc53836dac55a63ecc5d96b0abbcf8c9dd9e19ac0bda5d3/gg_transfer-0.2.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ffe984ca76a0ea13a47b8c8d8c61c70e7b1f47e4fb42448c9aec683053dc4919",
"md5": "749f3abdd5b10f7d111b237e6e2b362c",
"sha256": "11394cbb82a41627233664c1e30c8b1fc9deb1043fc38f7f9d87f7f45c5e5199"
},
"downloads": -1,
"filename": "gg_transfer-0.2.6.tar.gz",
"has_sig": false,
"md5_digest": "749f3abdd5b10f7d111b237e6e2b362c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 21934,
"upload_time": "2024-08-29T10:15:07",
"upload_time_iso_8601": "2024-08-29T10:15:07.665329Z",
"url": "https://files.pythonhosted.org/packages/ff/e9/84ca76a0ea13a47b8c8d8c61c70e7b1f47e4fb42448c9aec683053dc4919/gg_transfer-0.2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-29 10:15:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "matteotenca",
"github_project": "gg-transfer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "gg-transfer"
}
