{"id":31618066,"url":"https://github.com/grebtsew/tspec","last_synced_at":"2026-05-06T06:32:22.461Z","repository":{"id":317929190,"uuid":"1065515506","full_name":"grebtsew/TSpec","owner":"grebtsew","description":"Terminal spectrum and waterfall visualization of In-phase/Quadrature data.","archived":false,"fork":false,"pushed_at":"2025-10-03T22:29:06.000Z","size":16608,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-04T00:23:07.066Z","etag":null,"topics":["docker","docker-compose","python","rtl-sdr","server","spectrogram","spectrum","terminal","terminal-color","waterfall"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grebtsew.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-27T22:02:33.000Z","updated_at":"2025-10-03T22:29:09.000Z","dependencies_parsed_at":"2025-10-04T00:23:17.213Z","dependency_job_id":"ede66252-860f-4eb8-b866-281f2fc35991","html_url":"https://github.com/grebtsew/TSpec","commit_stats":null,"previous_names":["grebtsew/tspec"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/grebtsew/TSpec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grebtsew%2FTSpec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grebtsew%2FTSpec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grebtsew%2FTSpec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grebtsew%2FTSpec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grebtsew","download_url":"https://codeload.github.com/grebtsew/TSpec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grebtsew%2FTSpec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278621843,"owners_count":26017253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","docker-compose","python","rtl-sdr","server","spectrogram","spectrum","terminal","terminal-color","waterfall"],"created_at":"2025-10-06T13:45:20.527Z","updated_at":"2026-05-06T06:32:22.452Z","avatar_url":"https://github.com/grebtsew.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TSpec\nTSpec is a minimalist, high-performance terminal-based spectrum and waterfall display designed to run on any system, even without a GUI. It works seamlessly on older terminals and low-powered hardware, making it ideal for embedded systems or remote servers. With support for multiple stream formats and radio systems, TSpec ensures maximum flexibility while keeping resource usage minimal. TSpec also provides a wide range of features—see [features](#flags) for more details. Whether you need a quick visualization on a headless server or a lightweight monitoring tool, TSpec delivers fast, reliable, and portable spectrum analysis wherever you need it.\n\n\n\n![demogif](./docs/demo.gif)\n\n![CI](https://github.com/grebtsew/TSpec/actions/workflows/ci.yml/badge.svg)\n![license](https://img.shields.io/github/license/grebtsew/TSpec)\n![size](https://img.shields.io/github/repo-size/grebtsew/TSpec)\n![commit](https://img.shields.io/github/last-commit/grebtsew/TSpec)\n\n\n# Run (for simple usage)\n\nDownload executable [here](https://github.com/grebtsew/TSpec/releases) from latest release and get going. I recommend placing the application in system programs a using enviroment variables.\n\nWindows:\n```bash\nTSpec.exe [OPTIONS]\n```\n\nLinux:\n```bash\nTSpec [OPTIONS]\n```\n\n\n# Controls\n\nThe following demo is started using the following flags:\n```bash\n...\n```\n\n(control_demo)[./docs/control_demo.gif]\nTODO:\n- w,a,s,d - movement in spectrum\n- +,- - zoom in and out in freq\n- ,,. - zoom in and out in db\n- f - auto zoom focus on signals\n- c - clear frame, removes old symbols\n- x - random color theme\n- 1-9 - refresh-rate, 0 - unlimited\n- i-o - line-width (3d effect)\n- r - reset \n\n\n# Examples \nThese examples uses windows executable:\n\nMinimal features:\n```bash\nTSpec.exe \n```\nSetting symbols and sizes, using format raw\n```bash\nTSpec.exe --thresholds '\\-45:|,\\-50:-,\\-65:.' --waterfall-height 20 --bins 80 --spectrum-height 10 --format raw --freq-min 0 --freq-max 500000  --db-min -120 --db-max 0\n```\n\nUsing default color themes, calculate rssi and timestamp:\n```bash\nTSpec.exe --color-waterfall --color-spectrum --colormap inferno --spectrum-symbol \" \" --spectrum-symbol-color-background --rssi --timestamp\n```\n\nUsing custom color themes and line graph with set refresh rate:\n```bash\nTSpec.exe --color-waterfall  --color-spectrum --colormap inferno --spectrum-symbol \" \" --spectrum-symbol-color-background --format raw  --line-width 3 --line --format raw   --colormap custom --custom-colormap \"#000000,#aa0000,64\" --refresh-rate 10\n```\n\nUsing example modules:\n```bash\npython ./src/TSpec.py --bins 80 --spectrum-height 20 --waterfall-height 5 --input ./modules/source/random_source_module.py --format ./modules/parse/custom_parser_module.py\n```\n\n## Run (for developers, python and docker users)\nRun in python use:\n```bash\npython TSpec.py [OPTIONS]\n```\nOr in windows use the release .exe file, a corresponding file in release for linux users exist.\n\nRun in docker using:\n```bash\ndocker-compose up\n```\n\n\n## Installation (for developers or python users )\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/grebtsew/TSpec\ncd ./TSpec\n```\n2. Install required:\n```bash\npip install -r ./requirements.txt\n```\n\n3. Make sure the script is executable:\n```bash\nchmod +x TSpec.py\n```\n\n# Features\n\nThe table below describes all available command-line flags and their corresponding features.\n\n\n| Argument                             | Description                                                         | Default / Notes |\n| ------------------------------------ | ------------------------------------------------------------------- | --------------- |\n| `--address`                          | IP address of the radio device                                      | `127.0.0.1`     |\n| `--port`                             | TCP/UDP port                                                        | `5005`          |\n| `--format`                           | Stream format (`vita49`, `raw`, `simulator`)                        | `vita49`        |\n| `--bins`                             | Number of frequency bins                                            | `80`            |\n| `--waterfall-height`                 | Maximum waterfall rows                                              | `10`            |\n| `--color-waterfall`                  | Enable color in waterfall display                                   | -               |\n| `--color-spectrum`                   | Enable color in spectrum display                                    | -               |\n| `--colormap`                         | Colormap to use (`viridis`, `magma`, `plasma`, `inferno`, `custom`) | `viridis`       |\n| `--custom-colormap`                  | Custom colormap: startcolor,stopcolor,steps                         | -               |\n| `--spectrum-height`                  | Number of rows for spectrum                                         | `10`            |\n| `--spectrum-symbol`                  | Symbol used for spectrum bars or line                               | `.`             |\n| `--spectrum-symbol-color-background` | Display spectrum symbol with colored background                     | -               |\n| `--bar`                              | Display spectrum in bar mode                                        | Default         |\n| `--line`                             | Display spectrum in line mode (contour line)                        | -               |\n| `--line-width`                       | Vertical thickness of line in line mode                             | `1`             |\n| `--freq-min`                         | Minimum frequency to display (Hz)                                   | -               |\n| `--freq-max`                         | Maximum frequency to display (Hz)                                   | -               |\n| `--auto-zoom`                        | Automatically zoom to signal region                                 | -               |\n| `--auto-zoom-threshold`              | dB above noise floor considered signal                              | `10`            |\n| `--auto-zoom-iterations`             | Number of autozoom iterations (0 = infinite)                        | `0`             |\n| `--store`                            | Save incoming IQ data to a file                                     | -               |\n| `--load`                             | Load IQ data from a file instead of UDP                             | -               |\n| `--hide-spectrum`                    | Do not display spectrum output                                      | -               |\n| `--hide-waterfall`                   | Do not display waterfall output                                     | -               |\n| `--refresh-rate`                     | Maximum refresh rate in Hz                                          | None            |\n| `--max-delta-db`                     | Maximum allowed jump in dB per refresh                              | None            |\n| `--smoothing`                        | Apply exponential moving average smoothing (0.0 = off)              | `0.0`           |\n| `--timestamp`                        | Print timestamp with each frame                                     | -               |\n| `--decimate`                         | Use only every Nth sample to reduce sample rate                     | `1`             |\n| `--fft-size`                         | FFT size (default = length of input block)                          | None            |\n| `--window`                           | FFT window function (`hann`, `hamming`, `blackman`, `rectangular`)  | `hann`          |\n| `--no-normalize`                     | Don't normalize spectrum to 0 dB max                                | -               |\n| `--waterfall-scale`                  | Scale type for waterfall (`log` or `linear`)                        | `log`           |\n| `--waterfall-speed`                  | Number of waterfall updates to skip per frame                       |                 |\n| `--clear-on-new-frame`               | Determine if to clear terminal each frame. This might cause flimmer |                 |\n| `--freq-offset`                      | Frequency Offset                                                    |  0               |\n| `--block-size`                       | Block size (number of samples per FFT). Default = use fft-size or input length    | 0                |\n| `--db-min`                           | Minimum dB level for display (clip). If not set, auto or normalize is used       | None             |\n| `--db-max`                           | Maximum dB level for display (clip). If not set, auto or normalize is used       | None             |\n| `--waterfall-gamma`                   | Gamma correction for waterfall colors (default 1.0 = linear)                     | 1.0              |\n| `--dtype`                             | Data type of incoming IQ samples (float32, int16, int8). Default = float32       | float32          |\n| `--avg-blocks` | Average over N blocks for smoother display (1 = off) | 1 |\n| `--maxhold` | Show maximum value per bin across frames instead of current spectrum | False |\n| `--rssi` | Display RSSI (Received Signal Strength Indicator) of the shown spectrum instead of per-bin values | False |\n| `--ignore-missing-meta` | Ignore IQ blocks that are missing metadata instead of raising errors | False |\n| `--feature-symbol` | Symbol used to mark extracted features (e.g., peak) in the spectrum. | * |\n| `--feature-color` | Color for extracted feature (format: 'R,G,B' 0-255), overrides symbol color if set. | None |\n| `--feature-avg-offset` | Offset for feature extraction detection, threshold avg + this offset. | 5 |\nTODO:\n\n# Modules\nTODO:\n## Input modules\nTODO:\n## Parse modules\n\n\n# Features\n\n- Terminal-based **spectrum and waterfall display** with ASCII symbols or colored visualization.\n- Support for colormaps: `viridis`, `magma`, `plasma`, `inferno`, or custom colormaps.\n- Customizable thresholds and symbols for the waterfall.\n- Auto-zoom functionality that focuses on signals above the noise floor.\n- Ability to save incoming IQ data to a file and load IQ data from files for replay.\n- Adjustable display settings including spectrum height, waterfall height, symbol choice, and line/bar modes.\n- Supports maximum refresh rates and clamping of rapid dB changes for smoother visualizations.\nTODO:\n\n# Input\n\nThe input folder contains the following input-examples:\n- rtl-sdr example using minimized vita49\n- microphone data as raw\n- simulator data as raw\n- simulator data as simulator (own) format\n- simulator iqfile stream example data to file\n- soupy raw example for streaming soupySDR data over udp\n\n# System diagram\n\nTODO:\n\n# Dependencies\n\nThe only required dependency except for python3 is numpy for performing the FFT and handling data arrays more effectively. For testing and examples, some more libraries are needed!\n\n# Testing\nVital and core functionality are tested with pytest. To run tests yourself enter `Testing`-folder and run:\n```cmd\npytest .\n```\n\n# Format\nThis repository uses python `black` to keep code format.\n\n# License\nThe project uses MIT License, read more [here](./License).\n\n\n# Disclaimer\n\nLarge quantities of this code and documentation is generated using ChatGPT-5 mini 2025.\n\n\n\n@Grebtsew 2025\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrebtsew%2Ftspec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrebtsew%2Ftspec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrebtsew%2Ftspec/lists"}