HQPTuner: an improved configuration interface for HQPlayer Embedded

ohwowgorillas · August 9, 2026, 8:08am

I’m very, very excited to announce a very cool new feature that I’ve started work on.

Most of you already in this thread won’t care… but I think there are a lot of people out there that need it:

A SETUP WIZARD!

Someone from here in the Roon community reached out to me last week about expanding HQPTuner into something capable of not just making the HQPlayer experience easier for those who already know the ropes, but also making it easier on those who don’t.

The original idea was “can I just give you my hardware and have HQPTuner spit out the best settings possible?” to which the answer is no, there are no such thing as “the best” settings. But after a little back-and-forth, we’ve arrived at a concept that both simplifies the initial setup without pretending to provide anything optimized or ideal.

It’s been a while since many of us have had to set HQPlayer up, and most of us have probably blocked out the trauma of getting it to work to the point where we just say “oh, yeah, it’s easy.” Sure, for us, because we know what we’re doing. We already know the half dozen settings we actually need and where to find them, and know to ignore the other 300 that we don’t.

To the uninitiated, though, all of that blends together. They don’t know that it only really takes 4-5 different settings to get good sound output. All they see is a ton of different settings with no explanations and no arrow or pointer that says “start here.” I know for a fact that the setup phase alone has driven away many, many a potential user.

And HQPTuner can change that relatively easily: a wizard that walks you through from a fresh HQPlayer installation to the point at which you are ready to press play isn’t difficult. It’s a big feature, but it’s not a hard feature.

The outline would look something like:

How many setups do you have? That is, how many presets are you going to need?
For each preset, you’re walked through backend selection, device identification, rate limits, fixed vs adaptive volume, etc.
Load any EQ profiles per preset
Does your hardware have an Nvidia GPU and/or a CPU with E-cores?
A tour of the HQPTuner interface including how to use the filter narrowing system

…ending with the simple message “You can hit Play now. Enjoy the tunes :)”.

The person who reached out is willing to contribute resources and ideas, so hopefully this is something I can roll out in the next few weeks. They’re also willing to contribute greatly to the EQ Assistant, a fully optional, opt-in only AI bot capable of EQ tweaks and filter recommendations† based on qualitative complaints. It would also explain the reasoning behind each decision, ideally leaving the user better informed and ensuring that the concept acts more as training wheels than a crutch.

†Yes, filter recommendations are a minefield. The EQ Assistant would NOT work like “recommend the best classical filter”, it should just ask you to clarify what you consider “best”. Rather, you might say “This filter is too incisive, give me something smoother and more analog” and it would change a single axis, or prefer something that has “timbre” instead of “transients” as one of its qualities.

So, yeah, big things on the horizon. In the meantime, I’ll continue to patch bugs as I stumble over them and let people know how the feature’s development is coming along.

jussi_laako · August 9, 2026, 6:19pm

Ehm, sorry, but there is a description for each filter in the control app. And also in the manual, with some suggestions based on genre, etc…

And also the default settings are the most general purpose best ones, on purpose. So one doesn’t need to change filters or modulator at all from the default install to get what I consider best at the moment.

ohwowgorillas · August 9, 2026, 7:17pm

Ehm, sorry, but there is a description for each filter in the control app. And also in the manual, with some suggestions based on genre, etc…

Of course! And HQPTuner follows those suggestions faithfully. My filter narrowing feature is your manual’s filter table, just codified so people don’t need to cross reference things in their head. I’ve added nothing of my own.

The wizard’s necessity is more referencing the steps needed to get output per preset: rate limits, the 48kHz DSD setting, output mode, etc. Those are what are scattered around the stock UI with no explanations (except from manually parsing the manual). Some users have no confidence in going from a fresh installation to hitting play because all they see is 50 different settings and have no idea where to start. They can’t parse out the 4-5 they need to get output.

The point is just getting the user to the point where they can click Play and hear music. From there, they’re released into the HQPTuner interface with the full number of options to tweak to their own delight.

And also the default settings are the most general purpose best ones, on purpose. So one doesn’t need to change filters or modulator at all from the default install to get what I consider best at the moment.

I totally agree. The text, as written in the setup wizard’s draft right now, contains:

HQPTuner Hints: the default filters are superb all-arounders and are the defaults for a reason. You could even skip this part for now.

Users are guided to the page, shown how the narrowing system works, informed that the defaults are great, and then they’re free to do whatever they want.

It’s incredibly important to me that HQPTuner preserves and stays faithful to your work and vision of HQPlayer. I’m just a UI nerd who wanted his favorite program’s interface to look prettier, I do not have the qualifications or background to make sonic decisions on the user’s behalf and I’m not going anywhere near anything that resembles that.

ohwowgorillas · August 10, 2026, 12:53am

Yes, it’s time for your almost daily update this is v1.3.4:

HQPTuner grayed out invalid modulator selections (e.g., if you’re at DSD256, several modulators will fail to produce output so you can’t select them in HQPTuner) on the Output tab, but not in Live mode. That’s fixed so both behaviors are identical.
HQPTuner now alerts you when otherwise making bad choices, e.g., “The current settings are invalid: modulator AMSDM7EC 512+fs is incompatible with DSD128. HQPlayer cannot produce output.” This is possible by selecting the high rate-bound modulator and then dropping the output rate.
Further to that, ditherers that are suboptimal at various PCM rates are no longer grayed out. The daemon doesn’t throw errors with those combos like it does with the wrong modulator, it’s just not optimal. HQPTuner will now alert you, e.g., “The current settings are suboptimal: ditherer LNS15 is optimized for output rates >=8x, but your current rate is 4x.”
My previous change of having the currently loaded matrix profile stick around by default seems well received, however, it also incorrectly kept that matrix profile across preset loads, so you’d end up with a headphone EQ profile loaded on your speaker rig. Now, the matrix profile only sticks around when reloading the same preset.
Previously, saving a matrix profile gave no indication that a daemon restart was needed to complete the save. It would stage an Apply, but wouldn’t say anything about what was staged or why. Now, there’s a simple text warning, “Restart the engine (Apply) to finalize the save.” below the save box.
Text highlighting is suppressed when clicking and dragging on a knob.
Minor visual fixes

ohwowgorillas · August 13, 2026, 7:51am

I just dropped v1.4.0

First, I’m curious how many people use HQPTuner. I’ve switched the main image location from GHCR to Docker Hub, which reports how many pulls a certain version has.

Going forward, edit compose.yaml and remove ghcr.io/ from the image: line so it just says image: oh💩gorillas/hqptuner:latest. Except, y’know, replace the emoji with …

To be perfectly clear: HQPTuner contains no telemetry or data collection whatsoever and never will. This simply increments a counter whenever someone pulls the container image.

Moving on… changes! Lots of them!

Filter tooltips now show its properties as well: quality, genre, focus, etc. are all listed in the hover tip.
Matrix profiles can now have optional notes (“descriptions”) attached.
I fixed DAC corrections getting clobbered when loading NEW matrix profiles, but old profiles continued to be affected. This back-ports the fix into buggy matrix profiles on your first apply.
Improved log tail scrolling behavior and added a Copy button.
Filter favorites are now stored internally rather than per browser. The first browser to see the new version syncs its favorites to state/, then the rest get clobbered.
Filter narrowing settings persist between sessions (except Favorites only).
Filter lists no longer show the current filter if it’s narrowed out. That made it difficult to tell whether the current filter was still appropriate. Clicking away from the dropdown maintains the same filter.
Cleaned up some of the manual descriptions. I went real literal with “settings must match the manual verbatim” last time, so I ended up with things like “On Linux, the ALSA audio endpoint…” on the Network backend’s Output devices dropdown. Descriptions have been minimally adjusted to describe themselves, not other settings.
Live settings (sans matrix profiles, which can’t be loaded without live playback) are automatically restored after a device list refresh when auto-save is enabled.
Setting minimum buffers (short buffer = minimum or buffer time = -1) now shows a warning and asks you to confirm before the change. On advice from Jussi, these are specialty settings that are rarely justified and likely to break things, like they did in my case.
HQPTuner now displays the product version (currently 6.0.2) in System alongside the Engine version (6.0.4). It used to display the Engine version as though it were the product version, which was confusing.
The meter reading can optionally be turned off (HQPTUNER_METERING_ENABLED in compose.yaml). HQPTuner also drops the metering stream with no playback.
Miscellaneous bug fixes and visual enhancements.

I’ve also done quite a lot of reorganization:

The Resampling tab has been consumed by Output.
Things that were previously in the Output tab’s General card—the vast majority of which had nothing to do with output—have been shuffled around. The General card was eliminated.
- Output channels is now in Matrix
- PCM Gain Compensation is now in Volume>Adjustments, alongside Adaptive volume and Replay gain
- Timing settings have been moved to System>Timing
- UPnP freewheel has been moved to System>UPnP

I am open to any and all organizational ideas! If you don’t like this latest round of changes, tell me what part of your flow I just broke.

ohwowgorillas · August 14, 2026, 11:25pm

Aaaaand v1.6.0 now!

Added a “warning” letting users know that enabling Direct DSD forces the PCM chain to a fixed -3dB output volume. Only applies when not already using a -3dB fixed volume.
Added [ AND | OR ] switches to the Genre and Focus dropdown boxes to change the narrowing behavior of each.
Changed more boring checkboxes to cooler looking switches:
- Gain +6dB changed to “Source gain” with switch [ 0 dB | +6 dB ]
- IPv6 support > “Discovery” with switch [ IPv4 | +IPv6 ]
- DoP changed to “DSD support” with switch [ Native DSD | DSD over PCM (DoP) ]
- 48kHz DSD rates > “DSD rates” with switch [ 44.1kHz only | +48kHz family ]

The big change, though, is that I gave the “ratio” filter narrowing dropdown an overhaul. I realized four issues with the previous implementation:

It gave users the opposite of the behavior they needed. If your DAC doesn’t support 48kHz DSD rates, you want to hide filters that upsample to integer or 2x rates only. If you’re downsampling, you don’t want to see filters that only upsample. But the dropdown’s originally intended behavior was the opposite of what people actually need those descriptors for.
The default dropdown value read “Any ratio”, which was a lie: it showed all filters, not filters capable of doing any ratio.
There was no explanation anywhere about what any of this meant; someone new to HQPlayer could absolutely not suss out what these options do on their own.
It didn’t work! >.< None of the options actually did anything except “Upsample only”.

After a lot of wrestling over how to present these features and what they’re actually useful for, that dropdown is now three checkboxes which are all perfectly intelligible options:

Hide output rate-limited filters
Show only filters that support downsampling
Show only filters that support resampling uncommon source rates (e.g., 32kHz)

The first one hides all Integer-only and 2x-only filters; the second hides all upsampling-only filters; the third one shows Integer-only filters plus filters capable of any output rate. As always, if I’ve missed anything or you have a different use case, let me know and I’ll work it in.

So if your DAC doesn’t support 48kHz DSD rates but you’re in SDM output mode, you can now hide all the filters that don’t make sound with 48kHz-family sources. Better yet, when HQPTuner sees that you’re in SDM mode with no 48k-family support, it will auto-check “hide output rate-limited filters”. You can uncheck it for 44.1k-family source material; switching to PCM or Auto mode also unchecks this.

jussi_laako · August 14, 2026, 11:29pm

With Roon as a source, it it good to suggest “Idle time” of something else than “Default”. Although latest release forces 10 seconds if nothing else is set when Roon appears first time as a source.

Otherwise Roon is constantly stopping and restarting the entire playback engine, which is time consuming and heavy operation.

ohwowgorillas · August 14, 2026, 11:52pm

10 seconds

Wait… is it seconds, or milliseconds? The manual says “milliseconds”. Just checking.

Also, how would one determine when larger values are better? Watch the log for engine restarts between songs?

Otherwise that’s a super easy feature, thanks for the tip!

ohwowgorillas · August 15, 2026, 2:28am

We’re now on v1.7.0!

Fixed a bug where enabling 48kHz-family DSD rates did not actually leave the “ratio” classification above alone; it forced “hide rate-limited filters” on SDM mode regardless.
Added Jussi’s recommendation above: with Roon as the source and engine idle time at default, a warning appears recommending a value of 10 or longer.
Fixed some filter phase classifications.

Big things on the horizon, too I have, for example, reached out to Small Green Computer, who sell pre-packaged HQPlayer Embedded-compatible systems, about also including HQPTuner once he finally rolls out v6 support.

It also appears, based on at least a couple reports, that HQPTuner works just fine with v5 as well! Obviously the junk filter dropdown is empty and doesn’t work, but otherwise, it seems perfectly capable of controlling v5 at a basic level.

ffk · August 15, 2026, 3:24am

Seconds. Using Roon as source I like this set to 30.

jussi_laako · August 15, 2026, 8:53pm

Uhm, where? Yes, it is seconds.

Higher the better. But do not for example power off the DAC until 10+set seconds after stopping Roon playback so that you don’t power down things while HQPlayer is still playing. (if you don’t long-press the pause button in Roon, it will send stop request to HQPlayer 10 seconds after you have hit the pause button, which will then start the idle period in HQPlayer)

You could more like ask yourself how long it usually takes for you to select next thing to play? Usually one minute is enough. So that you avoid unnecessarily stopping and restarting the engine, which is rather heavy operation. The stop-play cycles generated by regular Roon operation are rather short, so 10 seconds is way enough for this. 10 seconds matches the common idle period used also by Roon and for example Apple’s CoreAudio (they will power down the audio hardware 10 seconds after it has got last audio).

P.S. You can stop immediately without idle time from HQPlayer Client by clicking the stop-button twice. Or if you click stop there after Roon has issued stop request.

ohwowgorillas · August 16, 2026, 11:05pm

Seconds.

Ah, yeah, that makes sense… and makes my second question about optimizing it automatically asinine.

Uhm, where?

In the daemon’s readme, it sets the time in milliseconds:

3.8 HQPLAYER_IDLE_TIME
Amount of time to run idle in milliseconds.

from hqplayerd-readme.txt, lines 1008 - 1009. I got confused between the two, my mistake. The daemon sets the value in ms, but the user-facing value is in seconds.

jussi_laako · August 16, 2026, 11:17pm

Ahh yes, I see where the confusion is coming from. In setting file it is in milliseconds. The GUI offers choices of 10000, 20000, 30000 and 60000 milliseconds. IOW, 10, 20, 30 and 60 seconds.

Yes, that’s right. So the value granularity is in milliseconds, but the sensible values are in seconds category.

It is also internally rounded to minimum internal granularity which is higher than a millisecond. This a bit like the ASIO buffer granularity thing. (value X must be multiple of Y)

ohwowgorillas · August 16, 2026, 11:45pm

Yes, it’s time for another new version v1.8.0 is now live!

Added small descriptors under certain features to further demystify. Examples: Dither “Low-level noise treatment”, Modulator “Builds the 1-bit stream”, Nx filters “Hi-res content (≥88.2 kHz)”, etc.
Traded out the old 1x/Nx “hires” filter narrowing for a simpler system: “1x sources: [ Both | Lossless | Lossy ]” determines whether to show, hide, or show only hi-res and mp3/mqa filters. Nx no longer has a way to show only hi-res filters, but those are easy enough to pick out visually.
DSD Sources sections in the PCM/SDM Chain cards are now collapsible, with a control in the Narrowing card for your sources: [ PCM only | +DSD ] with an explanation below. Defaults to PCM only with DSD sources collapsed.
Quality ≥3/5 is now the default narrowing setting for all filters; 1/5 and 2/5 filters are hidden by default. This can be overridden by selecting “Any quality” under the quality narrowing dropdown.
The 1x dropdown no longer shows only apodizing filters by default (apodizing narrowing default changed to “all”); you now need to tell HQPTuner when you need apodizing (HQPTuner still shows an alert with ≥10 apodizing events per track).
Card title bar heights are now identical across the program
Added unit “seconds” to Engine idle time
“none” filter option (PCM only) now permanently visible regardless of narrowing settings

Last but not last, @ponta will be happy to hear that I’ve made most of the cards in Live mode collapsible (engine health, narrow filters, playback). It’s not exactly rearranging cards like you asked, but it should allow you to reach the matrix profile at the bottom without needing to scroll for it (I hope, let me know… I use a 4K screen to develop). I do still intend to make them reorganizable one of these days!

ponta · August 17, 2026, 2:54pm

Thanks!

Since I mostly use a tablet, being able to reorder things would definitely be way better. Looking forward to the next update!

That said, it’s awesome to be able to hide items I don’t need—definitely a great update!

ohwowgorillas · August 18, 2026, 10:47am

I’ve just uploaded v1.9.0 with what I think might be HQPTuner’s best feature yet. In terms of my goal of making HQPlayer more accessible to newcomers, this one is absolutely massive:

Filter and shaper names in plain English.

I’ve spoken to several people who have installed HQPlayer Desktop, loaded up a playlist, checked the filter list, got intimidated, and then closed the program without ever clicking play. Yes, the defaults are awesome and they could have just not bothered, but the interface is, as with so many other things, of no assistance in helping users come to that conclusion.

Reading HQPlayer’s filters isn’t hard once you get the hang of it. In fact, it occurred to me that what I do in my head could easily be turned into code.

So now it is. This is toggled by setting the “Option style” button from “Standard” to “Simplified” in the Filter Narrowing card, underneath Apodizing.

Yes, it’s still filter jargon… but at least it’s legible filter jargon!

Not only is this far more parseable to newbies, but it dramatically lowers the mental energy needed for even me to sort them in my head. It also shifts the light in which I see the list in some really interesting ways, and makes me willing to experiment with things I had never even considered before.

I think this should be the default setting, but I want to get feedback first before making that change, so any thoughts people might have would be very welcome!

Traditional filter names are printed below the dropdown and in the tooltip so users can learn the official system for discussing recommendations and such.

P.S. @ponta check the top right corner of Live mode

EDIT

After some feedback from one of the people that previously noped out of the filter list that “I’d be inclined to choose things that make sense to me, like extended frequency response, and avoid things that don’t like Gaussian”, I’ve also added blurbs under each family and variant.

Examples:

Polyphase Sinc: The most variety and flexibility
Closed form: Direct interpolation maintains original samples
Classic oversampling: The filter type found in most DACs
Gaussian: Best balance of time and frequency accuracy, gentler transients
Half-band: Response reaches close to the cutoff; for clean, well-mastered sources
Gaussian half-band: Gaussian smoothness with a slightly leaky response reaching the cutoff

I also broke up the Misc category into four new families: analog-style, classic oversampling, polynomial, and minimum ringing. Misc now only holds FFT/“Frequency-domain brickwall”, ASRC/“Asynchronous, any rate” and None/“No resampling”.

Here’s a shot of all 5/5 filters:

This is v1.10.0, and it gets the approval of at least one person previously overwhelmed by the filter selection process.

ponta · August 19, 2026, 2:00pm

Perfect, Adam!

jussi_laako · August 19, 2026, 10:42pm

I’m not sure what “gentler” means here, but it gives fastest and most accurate transient/step response while simultaneously maintaining very good frequency domain response. So what would be less gentle here? If less gentle would be like “harsh”, then yes, Gaussian is not harsh, as the goal is to avoid transient distortions (that commonly make sound over-bright/harsh, or shimmery like sunlight on a scratched glass, or just plain congested on dense passages).

If you’d look for analogous compare to the traditional analog filters, “gauss” would be like Bessel and “ext2” would be like Butterworth.

ohwowgorillas · August 20, 2026, 1:29am

Yes, the intended meaning was to convey a sense of smoothness/lack of harshness.

This has been changed to “cleanest transients” for now, anyway.

I did worry that as soon as I tried to describe things in my own words, I’d run into confusion like this. I’ve obviously tried to rely on the manual as heavily as possible and to use my own words as sparingly as possible, but in certain cases I had to get creative (e.g. Polyphase Sinc Family: “The most variety and flexibility” is not exactly from the manual but it is at least objectively true). I think the vast majority should be agreeable but I’m sure that you could likely pick out a few spots where the wording could be improved for accuracy

ohwowgorillas · August 21, 2026, 8:08am

v1.11.0 is up

Added a strip in the Engine Health card which visualizes apodization event density. Automatically appears upon any apod event, and persists until playback stops or one full track without any events passes. Time axis is adjustable between 30s, 1m, 2m, 5m, and the full session/track.
Apodizing and half apodizing filters are now indicated by accent-colored badges: a circled A or ½ next to the filter name in the dropdowns (pic).
Filter ratings are now shown alongside their names in the dropdowns. Since this system uses stars, I changed the Favorites symbol to a heart (also pic).
I’ve also re-set the default Quality rating to Any quality; now all four dropdowns show all filters by default.
Filter/shaper families and variants can be collapsed in Simplified mode.
Simplified mode blurbs are now more accurate (thanks for your help, Jussi!)
Dither and Modulator dropdowns now have Simplified blurbs as well
Modulator favorites!
Stylistic overhaul of the new dropdown elements to align things better and make them easier on the eyes.

Examples of the new apod glyphs/quality ratings:

Please note: while these aren’t notated in the manual (iirc only 3/5 and up are notated), the daemon does return 1 and 2 star ratings for some filters. I haven’t made anything up and these are official numbers.

Please also keep in mind that quality ratings are relative!

And as always, enjoy the tunes