{"id":13596699,"url":"https://github.com/erdewit/HiFiScan","last_synced_at":"2025-04-09T20:31:17.887Z","repository":{"id":59074824,"uuid":"535276329","full_name":"erdewit/HiFiScan","owner":"erdewit","description":"Optimize the audio quality of your loudspeakers","archived":true,"fork":false,"pushed_at":"2023-11-29T14:59:45.000Z","size":1977,"stargazers_count":1002,"open_issues_count":2,"forks_count":29,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-09T12:03:49.721Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/erdewit.png","metadata":{"files":{"readme":"README.rst","changelog":null,"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}},"created_at":"2022-09-11T11:26:34.000Z","updated_at":"2025-04-08T23:48:18.000Z","dependencies_parsed_at":"2024-01-15T16:48:03.726Z","dependency_job_id":null,"html_url":"https://github.com/erdewit/HiFiScan","commit_stats":{"total_commits":70,"total_committers":1,"mean_commits":70.0,"dds":0.0,"last_synced_commit":"99179cda45ab76d279d7d2b354e27b1061767082"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erdewit%2FHiFiScan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erdewit%2FHiFiScan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erdewit%2FHiFiScan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erdewit%2FHiFiScan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/erdewit","download_url":"https://codeload.github.com/erdewit/HiFiScan/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248036064,"owners_count":21037092,"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","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":[],"created_at":"2024-08-01T16:02:41.008Z","updated_at":"2025-04-09T20:31:16.812Z","avatar_url":"https://github.com/erdewit.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"|PyVersion| |Status| |PyPiVersion| |License|\n\nIntroduction\n============\n\nThe goal of HiFiScan is to help equalize an audio system to get\nthe best possible audio quality from it.\nThere are two ways to do this:\n\n1. Manual: The realtime frequency response is displayed and\nthe peaks and troughs can be interactively equalized away.\n\n2. Automatic: The frequency response is measured and a correction\nis calculated. This correction is by default a phase-neutral finite impulse\nresponse (FIR) that can be imported into most equalizer programs.\n\nThe measuring is done by playing a \"chirp\" sound that sweeps\nacross all frequencies and recording how loud each frequency comes out\nof the speakers. A good microphone is needed, with a wide frequency range\nand preferably with a flat frequency response.\n\nThe equalization itself is not provided; It can be performed by an\nequalizer of your choice, such as\n`EasyEffects \u003chttps://github.com/wwmm/easyeffects/\u003e`_\nfor Linux,\n`Equalizer APO \u003chttps://sourceforge.net/projects/equalizerapo/\u003e`_\nand\n`Peace \u003chttps://sourceforge.net/projects/peace-equalizer-apo-extension/\u003e`_\nfor Windows, or\n`eqMac \u003chttps://eqmac.app/\u003e`_ for macOS.\n\nInstallation\n============\n\n::\n\n    pip install -U hifiscan\n\nThe program is started from a console by typing::\n\n    hifiscan\n\nAll functionality is also available for interactive use in\n`this Jupyter notebook \u003cchirp.ipynb\u003e`_.\n\nExamples\n========\n\nLaptop\n------\n\nLets first optimize the speakers of a laptop.\nThe laptop has tiny down-firing speakers and a massive\ncase resonance that makes it sound about as bad as it gets.\n\nThe sound is recorded with a USB studio microphone; The built-in\nmicrophone of the laptop is not suitable for this.\n\n.. image:: images/laptop_setup.jpg\n\nLetting the measurements run it becomes clear just how bad\nthe spectrum is, with a peak at 1 kHz about 20 dB above average.\nEvery 10 dB is a factor 10 in power, so 20 dB is a factor 100.\n\nThe low frequency is set to 200 Hz since the laptop can't possibly\noutput anything below this.\n\n.. image:: images/laptop-spectrum.png\n\nTo get an automatic correction, we go to the \"Impulse Response\" section\n(selectable in the lower left corner). From here it's possible to use\nall-default values and click straight on \"Export as WAV\" to get a\nperfectly adequate result.\n\nBut lets optimize a bit further for this laptop. There are various\ntradeoffs that can be made, one of which involves the **Duration**\nof the impulse. A longer duration gives better bass control,\nbut also adds more latency.\nThe latency added by the equalizer is halve the duration of the impulse.\nSince the laptop has no bass anyway, we choose a 22 ms duration for a\nsuper-low 11 ms latency. This is less time than it takes sound to travel\nfour meters and is good enough even for gaming or video-calls.\n\nWe also increase the **Range** to 27 dB to get just a little bit of\nextra equalization.\n\nThe lower graph (in brown) shows how the equalized spectrum is expected\nto be, and it looks nicely flattened.\n\n.. image:: images/laptop-IR.png\n\nSo lets export the impulse response and import\nit into EasyEffects (In Convolver effect: \"Impulses -\u003e Import Impulse\"\nand then \"Load\"):\n\n.. image:: images/Convolver.png\n\nWe go back to the spectrum measurement and store the uncorrected\nspectrum with the **Store** button (to compare with later measurements).\nMore measurements can be stored as well, for example where the microphone\nis placed in different locatations, The total average of the stored\nmeasurements is shown in orange\n\nMeasuring the equalized system gives this:\n\n.. image:: images/laptop-flattened-spectrum.png\n\nIt is seen that the equalization works by attenuation only:\nEverything gets chopped to some level under the top (27 dB here)\nand this flattens the whole landscape.\n\nAll this attenuation does decrease the total loudness, so the\nvolume has to be turned up to get the same loudness. This also\nbrings up the flanks of the spectrum and increases the effective\nfrequency range. There's a very welcome 40 Hz of extra bass and\na whole lot of treble:\n\n.. image:: images/laptop-spectrum-equivolume.png\n\nThis is the point to leave the graphs and start to listen to\nsome music. Is there an improvement? There are of course lots\nof different tastes in what sounds good, but for those who like\na neutrally balanced sound there is a huge improvement. Voices\nare also much easier to understand.\n\nThe lack of bass is somewhat offset by the\n`missing fundamental \u003chttps://en.wikipedia.org/wiki/Missing_fundamental\u003e`_\nphenomenon, were the brain \"adds\" a missing low frequency based on\nits higher frequency harmonics. It seems that by equalizing the\nharmonics the phantom bass gets equalized as well.\n\nHiFi Stereo\n-----------\n\nThe HiFi installation has four JBL surround loudspeakers wired\nin series as a 2x2 stereo setup, plus a subwoofer. The sound\ncan only be described as very dull, as if the tweeters are\nnot working.\n\nTo calibrate we use the same microphone as for the laptop,\nwhich is a Superlux E205UMKII.\nLets this time correct for any non-flatness of the microphone.\nAccording to the documentation\nit has this frequency response:\n\n.. image:: images/mic_response.png\n\nWe create a text file that describes the microphone's frequency response::\n\n  20 -1.5\n  150 0\n  4500 0\n  10000 4\n  17000 0\n  20000 -2\n\nThe file is imported with \"Corrections... -\u003e Mic Calibration -\u003e Load\".\nManifucturer-supplied calibration files can be imported here as well.\n\nMeasuring the spectrum bears out the concerning lack\nof treble:\n\n.. image:: images/stereo-spectrum.png\n\nSo lets go to the Impulse Response section to fix this.\n\nThe **Range** is set to 33 dB - this is an extreme value but what the heck.\n\nThe **Tapering** is left at 5. It pulls the flanks of the Impulse\nResponse closer to zero (visible in the green curve), which also has\na smoothing effect on the spectrum. A value less than 5 might leave\nthe flanks of the green curve too high and this can cause nasty\n`pre-echos \u003chttps://en.wikipedia.org/wiki/Pre-echo\u003e`_.\nA value higher than 5 might cause too much smoothing of the bass\nregion.\n\nThe **Smoothing** will also smooth the spectrum, but the smoothing is\ndone proportional to the frequency. It will smooth the bass region\nless, allowing for better precision there. A good smoothing value\ncan be judged from the Correction Factor graph (in red): It should\nbe smooth with nicely rounded corners, yet with enough detail.\n\nThe **Duration** is fiddled with until an acceptable bass response is\nreached (visible in lowest graph in brown).\n\n.. image:: images/stereo-ir.png\n\nAfter exporting the Impulse Response and importing it into\nEasyEffects the result looks promising.\n\n.. image:: images/stereo-spectrum-corrected.png\n\nWe turn up the volume to get the same loudness as before and\napply some visual smoothing to the spectrum for clarity.\nIt turns out that the tweeters can\ndo their job if only the amplifier drives them 100 times as hard.\n\n.. image:: images/stereo-final.png\n\nThe difference in sound quality is night and day. Music is really\nreally good now. For movies it brings very immersive\naction and excellent clarity of dialogue.\n\nAs mentioned in the introduction, the equalization is phase-\nneutral. This means that despite the heavy and steep equalization\nthere are no relative phase shifts added. The details in a\nlossless source of music (such as the bounces of a cymbal)\nremain as crisp as can be.\n\nAs an aside, the amplifier used is a $18 circuit board based on the\n`TPA3116D2 digital amplifier chip \u003chttps://www.ti.com/product/TPA3116D2\u003e`_.\nIt draws 1.1 Watt while playing which only increases if the subwoofer\nis really busy.\n\nBluetooth headphones\n--------------------\n\nHiFiScan is not intended for use with headphones. There is\nthe\n`AutoEq project \u003chttps://github.com/jaakkopasanen/AutoEq\u003e`_\nwith ready-made corrections for most headphones, Even so,\nit can be used for experiments. For example, I have very\nnice Dali IO-4 headphones that can be used with Bluetooth\nor passively with an analog audio cable. It sounds better with\nBluetooth, which suggests that some equalization\nis taking place. Lets measure this!\n\n.. image:: images/dali.jpg\n\nIt is seen that there is a indeed a bit of active tuning\ngoing on, although most of the tuning is done acoustically.\nIn orange is bluetooth and in cyan is the analog cable.\nThere's a wide -10dB attenuation at 1.8 kHz and a narrow -4dB one at 5.5 kHz.\nThis tuning can be applied to the analog signal to get the same sound as\nwith Bluetooth.\n\n.. image:: images/dali-spectrum.png\n\nUsing a target curve\n--------------------\n\nInstead of aiming for a flat spectrum, it's also possible to target\na specific curve. This is done by creating a text file with the target\ncurve and importing it with \"Corrections... -\u003e Target Curve -\u003e Load\".\nLets use this zig-zagging target curve::\n\n  300 -10\n  500 10\n  1000 5\n  2000 10\n  4000 10\n  6000 0\n  20000 -10\n\nIn the Impulse Response section we see in the lower graph that\na fit is made to the red line, which is the target curve.\n\n.. image:: images/target_IR.png\n\nThe impulse with the baked-in target spectrum is exported and imported\ninto EasyEffects. In orange is the original spectrum, in red is the target\nand in cyan the reshaped spectrum that tries to follow the target curve:\n\n.. image:: images/target_spectrum.png\n\n\n.. |PyPiVersion| image:: https://img.shields.io/pypi/v/hifiscan.svg\n   :alt: PyPi\n   :target: https://pypi.python.org/pypi/hifiscan\n\n.. |PyVersion| image:: https://img.shields.io/badge/python-3.8+-blue.svg\n   :alt:\n\n.. |Status| image:: https://img.shields.io/badge/status-stable-green.svg\n   :alt:\n\n.. |License| image:: https://img.shields.io/badge/license-BSD-blue.svg\n   :alt:\n\nCausality\n---------\n\nThe default is to create a phase-neutral (aka linear-phase)\nimpulse response. It's also possible to create a minimum-phase response.\nEven everything in between is possible. This is done with the **Causality**\nparameter, where 0% is phase-neutral and 100% is minimum-phase.\nBy varying the causality a smooth transition between the extremes is made:\n\n.. image:: images/causality-waveform.png\n\nThe latency decreases proportional to the causality.\nAt 100% the response becomes zero-latency and purely causal, where only the current\nand past sound samples are used. The pre-echo is eliminated at the price of\ntwice the post-echo.\nNote that despite the name of \"minimum-phase\"\nthis setting actually incurs the most phase distortion, which can get severe with\na steep equalization.\n\nA good compromise may be a causality of 40%, which reduces the pre-echo\nby about 6 dB while not phase-smearing too much.\nLet your ears be the judge of what sounds best.\n\nA tool for changing the causality of existing impulse responses (as WAV file)\nis found in \"Tools... -\u003e Change IR causality\".\n\nDisclaimer\n==========\n\nThe software is provided on the conditions of the simplified BSD license.\nAny blown speakers or shattered glasses are on you.\n\nEnjoy,\n\n:author: Ewald de Wit \u003cewald.de.wit@gmail.com\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferdewit%2FHiFiScan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferdewit%2FHiFiScan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferdewit%2FHiFiScan/lists"}