README.md (4056B)
1 Surroundize 2 =========== 3 4 Tool/PipeWire filter to convert stereo audio to surround, using 5 [Ffdshow][ffdshow tryout]'s DPL2 decoder or [Freesurround][]. 6 7 Building 8 -------- 9 10 Make sure you have a C++20 compiler and run. 11 12 make 13 14 If you don't have pipewire, you can compile just the standalone converter with 15 16 make surroundize-converter 17 18 Usage 19 ----- 20 21 There are two binaries currently. 22 23 ./surroundize-converter --options < input.raw > output.raw 24 25 Input must be RAW samples, in stereo 32-bit float format, output will be also 26 32-bit float samples (channel order depends on the decoder, it's recommended to 27 set the `--channel_map` option). The sample rate can be specified using the 28 --sample_rate option. 29 30 ./surroundize-pipewire --options 31 32 A pipewire filter to convert stereo surround to surround. There's no auto 33 connect, you have to use a patchbay or wireplumber scripts to connect it. This 34 program allows changing the options run-time by entering the new options on 35 stdin terminate by a newline. Note that multiple options can be specified on one 36 line, separated by spaces (note that there is currently no escape character, so 37 you can't specify values with spaces in them...). 38 39 Run any binary with `--help` to get a list of available options. As a 40 convenience, leading dashes are ignored, so you can use just `-option=value` or 41 `option=value` instead of `--option=value` if you're lazy. 42 43 Decoders 44 -------- 45 46 There are three decoders in this program (and one dummy which just outputs the 47 input stereo samples without changes, useful for troubleshooting). 48 49 `freesurround` is the higher quality one, supporting many surround formats, not 50 just 5.1. `ffdshow` is closer to what a real Dolby Pro Logic 2 decoder would do, 51 faster, and only supports 5.1 output. 52 53 With `freesurround` the most important option is probably `block_size` which 54 sets the amount of samples to be processed at once. It has to be a power of two 55 (128, 256, 512, 1024, 2048, 4096, 8192, etc.) and ideally close to 100 ms (the 56 default 4096 is suitable for 44.1 kHz and 48 kHz). The problem with this is that 57 freesurround itself has a `0.5 * block_size` latency in itself, so this would 58 translate to a total latency of 150 ms with 100 ms block sizes (139 ms with 44.1 59 kHz, 128 ms with 48 kHz) just from the surround conversion! It's OK if you're 60 just playing music or video where you can fix the A-V sync, but for realtime 61 input it's probably too much. Here are some results from my totally not 62 representative listening tests at 48 kHz sound: 63 64 4096: Reference, OK 65 66 2048: Fine unless you're an audiophile 67 68 1024: Artifacts start to become noticeable, but still OK for most purposes 69 70 512: It starts to sound like a badly compressed MP3 file and also weird 71 artifacts as sound sources move around. 72 73 256 and lower: Pretty bad, if 512 block size is still too much latency you 74 should look into the `ffdshow` decoder instead if you can live with 5.1 output 75 and worse surround separation. 76 77 `ffdshow` has way less controls than `freesurround`, one useful option here 78 (with pipewire) is the `--preamp` option, as ffdshow has a tendency to make the 79 output way louder than the input, resulting in clippings. Use it like 80 `--preamp=0.5` for a approx. -6 dB reduction. 81 82 `pw` is based on pipewire's built in upmixer. See the help and [pipewire docs][] 83 for more info. (You should probably enable `psd` otherwise it just copies the 84 fron to the rear channels). 85 86 LICENSE 87 ------- 88 89 Freesurround and ffdshow are licensed under the GPL 2+, and as such this whole 90 thing is GPL'd. See the wall of text in LICENSE for details and make sure you 91 don't violate your freedom™ while doing that. `pipewire.cpp` and 92 `pw_decoder.[ch]pp` contains code from pipewire, licensed under the MIT license. 93 Everything written by me is licensed under WTFPL 2.0, because fuck copyright 94 lawyers, not that it matters the slightest. 95 96 [ffdshow tryout]: https://ffdshow-tryout.sourceforge.net/ 97 [freesurround]: https://hydrogenaud.io/index.php/topic,52235.0.html 98 [pipewire docs]: https://docs.pipewire.org/page_man_pipewire-props_7.html