From: Sergey Matveev Date: Thu, 15 May 2025 12:03:47 +0000 (+0300) Subject: Simpler documentation format X-Git-Url: http://www.git.stargrave.org/?a=commitdiff_plain;h=ca2bde9af46655d3f401babd297072dd1f3dbc3e7448a0c0b853ee518f671016;p=vors.git Simpler documentation format --- diff --git a/doc/.gitignore b/doc/.gitignore deleted file mode 100644 index 19ec74a..0000000 --- a/doc/.gitignore +++ /dev/null @@ -1 +0,0 @@ -/vors.info diff --git a/doc/Features b/doc/Features new file mode 100644 index 0000000..cefbcea --- /dev/null +++ b/doc/Features @@ -0,0 +1,16 @@ +* Client-server architecture. All clients send their output to the + server, while it copies it to other clients. However, as a rule, there + is single client speaking at one time. +* 20ms frames with Opus-encoded audio with PLC (Packet Loss Concealment) + and DTX (discontinuous transmission) features enabled. Optional [VAD] + (voice activity detection). + => https://opus-codec.org/ Opus codec +* Noise-NK protocol-based 0-RTT single round-trip handshake over TCP + between client and server for creating authenticated encrypted channel + and authentication based on server's public key knowledge. + => http://noiseprotocol.org/ Noise protocol framework +* Fast ChaCha20 encryption with SipHash24 message authentication. +* Rooms, optionally password protected. Peers are able to broadcast + text message to everyone in the room. +* Ability to silence specified peer in the room. +* Fancy TUI client with mute-toggle ability by external utilities. diff --git a/doc/Install b/doc/Install new file mode 100644 index 0000000..444f952 --- /dev/null +++ b/doc/Install @@ -0,0 +1,52 @@ +VoRS is written on Go (at least 1.21 version is required), but also uses +wrapper on libopus library. Provided tarballs include its source code +and a fork of the gopkg.in/hraban/opus.v2 with the added ability to use +Decoder.SetComplexity call, that is required for ML-related optimisations. + +=> https://go.dev/ Go +=> https://opus-codec.org/ libopus +=> https://wiki.hydrogenaud.io/index.php?title=Opus Opus improvements +=> https://github.com/hraban/opus gopkg.in/hraban/opus.v2 +=> https://opus-codec.org/demo/opus-1.5/ ML-related optimisations + +Audio recording and playback is done through external utilities, capable +of reading/writing raw audio samples from stdin/stdout. SoX'es rec and +play are used by default. You can use anything you want by overriding +them with -rec and -play options to vors-client. + +=> https://sourceforge.net/projects/sox/ SoX + + $ version=3.1.0 + $ [fetch|wget] http://www.vors.stargrave.org/download/vors-$version.tar.zst + $ [fetch|wget] http://www.vors.stargrave.org/download/vors-$version.tar.zst.sig + [verify signature] + $ tar xf vors-$version.tar.zst + $ cd vors-$version + $ ./build + $ mv bin/vors-* $PATH/bin + +I heard that some proprietary systems can not create statically linked +binaries. You can use mk-non-static script to remove the need of static +linking. + + $ cd vors-$version + $ ./mk-non-static + $ ./build + +<<[download] + +<<[Integrity] + +Also there is Yggdrasil accessible address: http://y.www.vors.stargrave.org. +=> https://yggdrasil-network.github.io/ Yggdrasil + +You can obtain development source code with + git clone git://git.stargrave.org/vors.git +You can also use +anongit@master.git.stargrave.org:stargrave.org/vors.git +anongit@slave.git.stargrave.org:stargrave.org/vors.git +anongit@master.git.cypherpunks.su:stargrave.org/vors.git +anongit@slave.git.cypherpunks.su:stargrave.org/vors.git +git://git.cypherpunks.su/vors.git +git://y.git.stargrave.org/vors.git +git://y.git.cypherpunks.su/vors.git URLs instead. diff --git a/doc/Integrity b/doc/Integrity new file mode 100644 index 0000000..ca8df30 --- /dev/null +++ b/doc/Integrity @@ -0,0 +1,9 @@ +You *have to* verify downloaded tarballs authenticity to be sure that +you retrieved trusted and untampered software. OpenSSH .sig signature +[PUBKEY-SSH.pub] and its OpenPGP [PUBKEY-SSH.pub.asc] made with the key +above. Its fingerprint: SHA256:qmlbyzvDRNXGJNxteapAWOmJRrBrZ7afLsEqr36M6kA. + +=> https://www.openssh.com/ OpenSSH + +$ ssh-keygen -Y verify -f PUBKEY-SSH.pub -I vors@stargrave.org -n file \ + -s vors-$version.tar.zst.sig http://noiseprotocol.org/ Noise protocol framework + +* Client sends "VoRS v3" to the socket. Just a magic number. + +* All next messages are Netstring encoded strings. Most of them contain + netstring encoded sequence of netstrings if multiple values are expected: + NS(NS(arg0) || NS(arg1) || ...) + => http://cr.yp.to/proto/netstrings.txt Netstring + +* Client sends initial Noise handshake message with his username, room + name and optional BLAKE2s-256 hash of the room's password (or an empty + string) as a payload: ["USERNAME", "ROOM", BLAKE2s(PASSWORD)]. + +* Server answers with final noise handshake message with the ["COOKIE", + COOKIE], or ["ERR", MSG] failure message. It may reject a client if + there are too many peers, its name is already taken or it provided an + invalid room's password. + +* The 128-bit cookie is sent by client over UDP to the server every + second. If UDP packets are lost, then no connection is possible and + after a timeout the server drops the TCP connection. That cookie means: + + * confirmation of successful handshake on client side; + * UDP hole punching of stateful firewall or NAT; + * fact of client's UDP traffic ability to reach the server; + * client's UDP address knowledge (after passing NAT, its port may + differ from known to client one) + +* Server replies with ["SID", X], where X is single byte stream number + client must use. + +* ["PING"] and ["PONG"] messages are then sent every ten seconds as a heartbeat. + +S <- C : e, es, NS(NS("USERNAME") || NS("ROOM") || NS("PASSWORD")) +S -> C : e, ee, NS(NS("COOKIE") || NS(COOKIE)) +S <- C : UDP(COOKIE) +S -> C : NS(NS("SID") || NS(X)) + +S <- C : NS(NS("PING")) +S -> C : NS(NS("PONG")) +S <> C : ... + +S -> C : NS(NS("ADD") || NS(SID) || NS(USERNAME) || NS(KEY)) +S -> C : ... + +S -> C : NS(NS("DEL") || NS(SID)) +S -> C : ... + +Every second the client sends UDP packet with his single-byte stream +identifier, even if it's muted. That may help punching holes in stateful +firewalls. + +Clients are notified about new peers appearance with "ADD" commands, +telling their SIDs, usernames and keys. "DEL" notifies about leaving +peers. "MUTED", "UNMUTED" notifies peer's mute toggling. "CHAT" +broadcasts the message in the room. diff --git a/doc/Usage b/doc/Usage new file mode 100644 index 0000000..a3252a0 --- /dev/null +++ b/doc/Usage @@ -0,0 +1,44 @@ +* Generate server's keypair. And share its public key among users. + Fact of server's public key knowledge means ability to connect to it. + + $ vors-keygen | tee key | vors-keygen -pub | read pub + $ vors-server -key key -bind [2001:db8::1]:12978 + +* Client uses external commands for reading from microphone and playing + it back. By default it uses SoX'es "rec" and "play" commands. + + Pay attention that VoRS expects *ONLY* one channel, 48kHz, 16-bit + signed little-endian audio format. Empty strings in -rec/-play options + mean no recording/playback attempts. + + -play command is spawned for each participant. + Your OS should mix their output together. + +* Start the client, providing server's public key and our username: + + $ vors-client -srv "[2001:db8::1]:12978" -pub $pub -name NAME + + Pressing F10 in server/client TUIs means quitting. + Pressing F1 in client means "mute" toggling. + Cycling through chat windows and peers in client is done by Tab. + Pressing Enter on the peer silences it locally. + +* -room allows you to join non-root room. + -passwd allows you to protect it with provided password. + +* -mute-toggle allows you to toggle mute by external utilities. For + example you can use suckless minimalistic sxhkd daemon to capture X11 + key events and execute commands: + => https://github.com/baskerville/sxhkd sxhkd + + $ mkfifo /tmp/vors-mute-toggle.fifo + $ cat >sxhkd.cfg < https://github.com/dudik/herbe herbe diff --git a/doc/VAD b/doc/VAD new file mode 100644 index 0000000..908271b --- /dev/null +++ b/doc/VAD @@ -0,0 +1,15 @@ +Voice Activity Detection is off by default. You can use the +"vors-vad [-rec ...] THRES" command with feeding audio record in its +stdin. It will print calculated sound RMS value if it exceeds the THRES +threshold. So you can manually try various THRES values to see when it +is comfortable to detect your voice. Pass the desired THRES value to +-vad option of vors-client. + + $ vors-vad 100 + [talk and see if threshold is low/high enough] + [it is too sensible, let's try higher one] + + $ vors-vad 200 + [perfect!] + + $ vors-client -vad 200 [...] diff --git a/doc/download b/doc/download new file mode 100644 index 0000000..0c907a9 --- /dev/null +++ b/doc/download @@ -0,0 +1,9 @@ +3.1.0 | 2024-05-15 | 7200 KiB + => download/vors-3.1.0.tar.zst.meta4 + => download/vors-3.1.0.tar.zst + => download/vors-3.1.0.tar.zst.sig + +2.3.0 | 2024-04-16 | 7192 KiB + => download/vors-2.3.0.tar.zst.meta4 + => download/vors-2.3.0.tar.zst + => download/vors-2.3.0.tar.zst.sig diff --git a/doc/download.texi b/doc/download.texi deleted file mode 100644 index 02b09be..0000000 --- a/doc/download.texi +++ /dev/null @@ -1,14 +0,0 @@ -@multitable {XXXXX} {XXXX-XX-XX} {XXXX KiB} {meta4 tar ssh} -@headitem Version @tab Date @tab Size @tab Tarball - -@item 3.1.0 @tab 2024-05-15 @tab 7200 KiB @tab - @url{download/vors-3.1.0.tar.zst.meta4, meta4} - @url{download/vors-3.1.0.tar.zst, tar} - @url{download/vors-3.1.0.tar.zst.sig, ssh} - -@item 2.3.0 @tab 2024-04-16 @tab 7192 KiB @tab - @url{download/vors-2.3.0.tar.zst.meta4, meta4} - @url{download/vors-2.3.0.tar.zst, tar} - @url{download/vors-2.3.0.tar.zst.sig, ssh} - -@end multitable diff --git a/doc/features.texi b/doc/features.texi deleted file mode 100644 index 8608dc6..0000000 --- a/doc/features.texi +++ /dev/null @@ -1,28 +0,0 @@ -@node Features -@unnumbered Features - -@itemize - -@item Client-server architecture. All clients send their output to the -server, while it copies it to other clients. However, as a rule, there -is single client speaking at one time. - -@item 20ms frames with @url{https://opus-codec.org/, Opus}-encoded audio -with PLC (Packet Loss Concealment) and DTX (discontinuous transmission) -features enabled. Optional @ref{VAD} (voice activity detection). - -@item @url{http://noiseprotocol.org/, Noise}-NK protocol-based 0-RTT -single round-trip handshake over TCP between client and server for -creating authenticated encrypted channel and authentication based on -server's public key knowledge. - -@item Fast ChaCha20 encryption with SipHash24 message authentication. - -@item Rooms, optionally password protected. Peers are able to broadcast -text message to everyone in the room. - -@item Ability to silence specified peer in the room. - -@item Fancy TUI client with mute-toggle ability by external utilities. - -@end itemize diff --git a/doc/index b/doc/index new file mode 100644 index 0000000..b2e8054 --- /dev/null +++ b/doc/index @@ -0,0 +1,48 @@ +VoRS -- Vo(IP) Really Simple. +Very simple and usable multi-user VoIP solution. +Some kind of alternative to Mumble without gaming-related features. +=> https://www.mumble.info/ Mumble + +But why? SIP-based solutions are pretty complicated to setup, because +they are not made for simple tasks like sudden voice chats between a +few people. WebRTC-based solutions are insane bloated incredible +monsters by complexity and size, hardly possible to debug and having +frequent compatibility problems. They work mainly only if you use the +same kind of software and codecs, for example Chromium, that requires +dozens of gigabytes of disk space and much RAM, CPU time to build it. +Taking an enormous amount of CPU power to slowly work with it. Is not +it pure insanity for such relatively simple task? + +Mumble has wonderful simplicity and workability, but its client is +written on Qt, which requires hundreds of megabytes of additional +libraries to build it up. And users tend to complain about its newer +client versions quality and convenience. + +So let's write as simple VoIP talking client as it is possible, without +compromising convenience and simplicity for the user! I just want a +simple command, which only requires to specify the server's address with +the key to just immediately talk with someone. + +* No GUI requirement. Why would someone need a GUI for voice + application? But a fancy real-time refreshing TUI would be desirable. + Mumble tends to output no information, sometimes hiding the fact of a + problem and that everything stopped working. +* Mono-cypher, mono-codec protocol. +* Maximal easiness of usage: here is your address, key, do me good. + +VoRS is copylefted free software licenced under GNU Affero GPLv3. +It should work on all POSIX-compatible systems. + +=> https://www.gnu.org/philosophy/pragmatic.html Copyleft +=> https://www.gnu.org/philosophy/free-sw.html Free software +=> https://www.gnu.org/licenses/agpl.html GNU Affero GPLv3 +=> https://en.wikipedia.org/wiki/POSIX POSIX + +Server (above) and two clients (left and right) in a terminal multiplexer: +img screenshots/example.webp Server and two clients + +[Features] +[Install] +[Usage] +[VAD] +[Protocol] diff --git a/doc/index.texi b/doc/index.texi deleted file mode 100644 index baa63b7..0000000 --- a/doc/index.texi +++ /dev/null @@ -1,67 +0,0 @@ -\input texinfo -@settitle VoRS - -@copying -Copyright @copyright{} 2024-2025 @email{stargrave@@stargrave.org, Sergey Matveev} -@end copying - -@node Top -@top VoRS - -VoRS -- Vo(IP) Really Simple. -Very simple and usable multi-user VoIP solution. -Some kind of alternative to @url{https://www.mumble.info/, Mumble} -without gaming-related features. - -But why? SIP-based solutions are pretty complicated to setup, because -they are not made for simple tasks like sudden voice chats between a -few people. WebRTC-based solutions are insane bloated incredible -monsters by complexity and size, hardly possible to debug and having -frequent compatibility problems. They work mainly only if you use the -same kind of software and codecs, for example Chromium, that requires -dozens of gigabytes of disk space and much RAM, CPU time to build it. -Taking an enormous amount of CPU power to slowly work with it. Is not -it pure insanity for such relatively simple task? - -Mumble has wonderful simplicity and workability, but its client is -written on Qt, which requires hundreds of megabytes of additional -libraries to build it up. And users tend to complain about its newer -client versions quality and convenience. - -So let's write as simple VoIP talking client as it is possible, without -compromising convenience and simplicity for the user! I just want a -simple command, which only requires to specify the server's address with -the key to just immediately talk with someone. - -@itemize - -@item No GUI requirement. Why would someone need a GUI for voice -application? But a fancy real-time refreshing TUI would be desirable. -Mumble tends to output no information, sometimes hiding the fact of a -problem and that everything stopped working. - -@item Mono-cypher, mono-codec protocol. - -@item Maximal easiness of usage: here is your address, key, do me good. - -@end itemize - -VoRS is -@url{https://www.gnu.org/philosophy/pragmatic.html, copylefted} -@url{https://www.gnu.org/philosophy/free-sw.html, free software} -licenced under @url{https://www.gnu.org/licenses/agpl.html, GNU Affero GPLv3}. -It should work on all -@url{https://en.wikipedia.org/wiki/POSIX, POSIX}-compatible systems. - -@float -@image{screenshots/example,,,Server and two clients,.webp} -@caption{Server (above) and two clients (left and right) in a terminal multiplexer} -@end float - -@include features.texi -@include install.texi -@include usage.texi -@include vad.texi -@include proto.texi - -@bye diff --git a/doc/install.texi b/doc/install.texi deleted file mode 100644 index 4b6add8..0000000 --- a/doc/install.texi +++ /dev/null @@ -1,48 +0,0 @@ -@node Install -@unnumbered Install - -VoRS is written on @url{https://go.dev/, Go} (at least 1.21 version is -required), but also uses wrapper on @url{https://opus-codec.org/, -libopus} library. Provided tarballs include its source code -(@url{https://wiki.hydrogenaud.io/index.php?title=Opus, look} how many -improvements Opus got over the years) and a fork of the -@url{https://github.com/hraban/opus, gopkg.in/hraban/opus.v2} with the -added ability to use @code{Decoder.SetComplexity} call, that is required -for @url{https://opus-codec.org/demo/opus-1.5/, ML-related} optimisations. - -Audio recording and playback is done through external utilities, capable -of reading/writing raw audio samples from stdin/stdout. -@url{https://sourceforge.net/projects/sox/, SoX}'es @command{rec} and -@command{play} are used by default. You can use anything you want by -overriding them with @option{-rec} and @option{-play} options to -@command{vors-client}. - -@example -$ [fetch|wget] http://www.vors.stargrave.org/download/vors-@value{VERSION}.tar.zst -$ [fetch|wget] http://www.vors.stargrave.org/download/vors-@value{VERSION}.tar.zst.sig -[verify signature] -$ tar xf vors-@value{VERSION}.tar.zst -$ cd vors-@value{VERSION} -$ ./build -$ mv bin/vors-* $PATH/bin -@end example - -I heard that some proprietary systems can not create statically linked -binaries. You can use @command{mk-non-static} script to remove the need -of static linking. - -@example -$ cd vors-@value{VERSION} -$ ./mk-non-static -$ ./build -@end example - -@include download.texi -@include integrity.texi - -Also there is @url{https://yggdrasil-network.github.io/, Yggdrasil} -accessible address: @url{http://y.www.vors.stargrave.org}. - -You can obtain development source code with -@command{git clone git://git.stargrave.org/vors.git} -(also you can use @url{https://git.stargrave.org/vors.git}). diff --git a/doc/integrity.texi b/doc/integrity.texi deleted file mode 100644 index 59815f8..0000000 --- a/doc/integrity.texi +++ /dev/null @@ -1,11 +0,0 @@ -You @strong{have to} verify downloaded tarballs authenticity to be sure -that you retrieved trusted and untampered software. -@url{https://www.openssh.com/, OpenSSH} @file{.sig} signature -@url{PUBKEY-SSH.pub, Public key} and its OpenPGP -@url{PUBKEY-SSH.pub.asc, signature} made with the key above. -Its fingerprint: @code{SHA256:qmlbyzvDRNXGJNxteapAWOmJRrBrZ7afLsEqr36M6kA}. - -@example -$ ssh-keygen -Y verify -f PUBKEY-SSH.pub -I vors@@stargrave.org -n file \ - -s vors-@value{VERSION}.tar.zst.sig C : e, ee, NS(NS("COOKIE") || NS(COOKIE)) -S <- C : UDP(COOKIE) -S -> C : NS(NS("SID") || NS(X)) - -S <- C : NS(NS("PING")) -S -> C : NS(NS("PONG")) -S <> C : ... - -S -> C : NS(NS("ADD") || NS(SID) || NS(USERNAME) || NS(KEY)) -S -> C : ... - -S -> C : NS(NS("DEL") || NS(SID)) -S -> C : ... -@end example - -Every second the client sends UDP packet with his single-byte stream -identifier, even if it's muted. That may help punching holes in stateful -firewalls. - -Clients are notified about new peers appearance with @code{ADD} -commands, telling their SIDs, usernames and keys. @code{DEL} notifies -about leaving peers. @code{MUTED}, @code{UNMUTED} notifies peer's mute -toggling. @code{CHAT} broadcasts the message in the room. diff --git a/doc/usage.texi b/doc/usage.texi deleted file mode 100644 index a7b2401..0000000 --- a/doc/usage.texi +++ /dev/null @@ -1,63 +0,0 @@ -@node Usage -@unnumbered Usage - -@itemize - -@item - Generate server's keypair. And share its public key among users. - Fact of server's public key knowledge means ability to connect to it. - -@example -$ vors-keygen | tee key | vors-keygen -pub | read pub -$ vors-server -key key -bind [2001:db8::1]:12978 -@end example - -@item - Client uses external commands for reading from microphone and - playing it back. By default it uses SoX'es @command{rec} and - @command{play} commands. - - Pay attention that VoRS expects @strong{ONLY} one channel, 48kHz, - 16-bit signed little-endian audio format. Empty strings in - @option{-rec}/@option{-play} options mean no recording/playback - attempts. - - @command{-play} command is spawned for each participant. Your OS - should mix their output together. - -@item - Start the client, providing server's public key and our username: - -@example -$ vors-client -srv "[2001:db8::1]:12978" -pub $pub -name NAME -@end example - - Pressing F10 in server/client TUIs means quitting. - Pressing F1 in client means "mute" toggling. - Cycling through chat windows and peers in client is done by Tab. - Pressing Enter on the peer silences it locally. - -@item - @option{-room} allows you to join non-root room. - @option{-passwd} allows you to protect it with provided password. - -@item - @option{-mute-toggle} allows you to toggle mute by external - utilities. For example you can use suckless minimalistic - @url{https://github.com/baskerville/sxhkd, sxhkd} daemon to capture - X11 key events and execute commands: - -@example -$ mkfifo /tmp/vors-mute-toggle.fifo -$ cat >sxhkd.cfg <VERSION ######################################################################## -cd doc -cat >download.texi <doc/download < http://www.vors.stargrave.org EOF +( cd doc ; ZK_DO_BACKS=0 $HOME/work/zk/zk info ) >vors.info -mkinfo() { - ${MAKEINFO:-makeinfo} --plaintext \ - --set-customization-variable ASCII_PUNCTUATION=1 \ - -D "VERSION `cat ../VERSION`" $@ -} - -texi=$(mktemp) - -cat >$texi < download/$tarball.meta4 + => download/$tarball + => download/$tarball.sig EOF mv $tmp/$tarball $tmp/"$tarball".sig $tarball.meta4 $cur/doc/vors.html/download