From 407d0251b44b18ea285c18f240bf10a54f9ff688 Mon Sep 17 00:00:00 2001 From: alemi Date: Mon, 18 Sep 2023 01:40:34 +0200 Subject: [PATCH] docs: updated README.md --- README.md | 65 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 37 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 8ef243e..e48e1c1 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,12 @@ # scope-tui -A simple oscilloscope/vectorscope in your terminal +A simple oscilloscope/vectorscope/spectroscope in your terminal ![scope-tui interface](https://cdn.alemi.dev/scope-tui-wide.png) Currently only for Linux (with Pulseaudio) +See it in action [here](https://cdn.alemi.dev/scope-tui-oscilloscope-music.webm) with [Jerobeam Fenderson - Planets](https://youtu.be/XziuEdpVUe0) (oscilloscope music) + ## Why I really love [cava](https://github.com/karlstav/cava). It provides a crude but pleasant frequency plot for your music: just the bare minimum to see leads solos and basslines. I wanted to also be able to see waveforms, but to my knowledge nothing is available. There is some soundcard oscilloscope software available, but the graphical GUI is usually dated and breaks the magic. @@ -19,21 +21,23 @@ Arguments: [DEVICE] Audio device to attach to Options: - -b, --buffer Size of audio buffer, and width of scope [default: 8192] - -r, --range Max value, positive and negative, on amplitude scale [default: 20000] - --scatter Use vintage looking scatter mode instead of line mode - --vectorscope Combine left and right channels into vectorscope view - --tune Tune buffer size to be in tune with given note (overrides buffer option) - --channels Number of channels to open [default: 2] - --sample-rate Sample rate to use [default: 44100] - --server-buffer Pulseaudio server buffer size, in block number [default: 32] - --triggering Start drawing at first rising edge - --threshold Threshold value for triggering [default: 0] - --no-reference Don't draw reference line - --no-ui Hide UI and only draw waveforms - --no-braille Don't use braille dots for drawing lines - -h, --help Print help information - -V, --version Print version information + -b, --buffer Size of audio buffer, and width of scope [default: 8192] + -r, --range Max value, positive and negative, on amplitude scale [default: 20000] + --scatter Use vintage looking scatter mode instead of line mode + --show-peaks Show peaks for each channel as dots + --tune Tune buffer size to be in tune with given note (overrides buffer option) + --channels Number of channels to open [default: 2] + --sample-rate Sample rate to use [default: 44100] + --server-buffer Pulseaudio server buffer size, in block number [default: 32] + --triggering Start drawing at first rising edge + --threshold Threshold value for triggering [default: 0] + --check-depth Length of trigger check in samples [default: 1] + --falling-edge Trigger upon falling edge instead of rising + --no-reference Don't draw reference line + --no-ui Hide UI and only draw waveforms + --no-braille Don't use braille dots for drawing lines + -h, --help Print help information + -V, --version Print version information ``` The audio buffer size directly impacts resource usage, latency and refresh rate and its limits are given by the audio refresh rate. Larger buffers are slower but less resource intensive. A good starting value might be `8192` or tuning to the 0th octave. @@ -42,21 +46,26 @@ To change audio buffer size, the PulseAudio client must be restarted. Because of ## Controls * Use `q` or `CTRL+C` to exit -* Use `t` to toggle triggered mode -* Use `` to pause and resume display -* Use `` and `` to increase or decrease time range by 25 -* Use `` and `` to increase or decrease amplitude scale by 250 -* Use `` and `` to increase or decrease threshold by 250 - * Combine arrows with `` to increase or decrease by x4 - * Combine arrows with `` to increase or decrease by /5 - * Press `` to restore width and scale to default values -* Use `v` to toggle vectorscope mode * Use `s` to toggle scatter mode -* Use `b` to toggle braille characters * Use `h` to toggle interface * Use `r` to toggle reference lines -* Use `` to show ui and revert to oscilloscope -* Use `` to reset all options to startup values +* Use `` to pause and resume display +* Use `` and `` to increase or decrease X range +* Use `` and `` to increase or decrease Y range +* Use `` to revert view settings to defaults +* Use `` to switch between modes: + * **Oscilloscope**: + * Use `t` to toggle triggered mode + * Use `e` to switch edge-triggering mode (rise/falling) + * Use `p` to toggle peaks display + * Use `` and `` to increase or decrease trigger threshold + * Use `-`/`_` and `=`/`+` to increase or decrease trigger debouncing + * **Spectroscope**: + * Use `` and `` to increase or decrease averaging count + * **Vectorscope**: +* Combine increment/decrement commands with `` to increase or decrease by x10 +* Combine increment/decrement commands with `` to increase or decrease by x5 +* Combine increment/decrement commands with `` to increase or decrease by x 1/5 # About precision While "scatter" plot mode is as precise as Pulseaudio and the terminal lets us be, "line" plot mode simply draws a straight line across points, meaning high frequencies don't get properly represented.