Merge branch 'DEVELOPMENT'

Makefile

@@ -1,10 +1,11 @@
 #!/usr/bin/make -f
 OPTIMIZATIONS ?= -msse -msse2 -mfpmath=sse -ffast-math -fomit-frame-pointer -O3 -fno-finite-math-only
 PREFIX ?= /usr/local
-CFLAGS ?= $(OPTIMIZATIONS) -Wall # -g3 -DDEBUG
+CFLAGS ?= $(OPTIMIZATIONS) -Wall
 
 STRIP?=strip
 STRIPFLAGS?=-s
+DEBUG?=0
 
 nrepel_VERSION?=$(shell git describe --tags HEAD 2>/dev/null | sed 's/-g.*$$//;s/^v//' || echo "LV2")
 ###############################################################################
@@ -15,6 +16,9 @@ LOADLIBES=-lm
 LV2NAME=nrepel
 BUNDLE=nrepel.lv2
 BUILDDIR=build/
+SRCDIR=src/
+TTLDIR=lv2ttl/
+DOCDIR=doc/
 targets=
 
 UNAME=$(shell uname)
@@ -54,9 +58,16 @@ ifeq ($(shell pkg-config --exists fftw3f || echo no), no)
 endif
 
 override CFLAGS += -fPIC -std=c99
-override CFLAGS += `pkg-config --cflags lv2`
+override CFLAGS += `pkg-config --cflags lv2 fftw3f`
 override LOADLIBES += `pkg-config --cflags --libs fftw3f`
 
+#for debug building
+ifeq ($(DEBUG), 1)
+  override CFLAGS += -g3 -DDEBUG
+else
+  override CFLAGS += -DNDEBUG
+endif
+
 # build target definitions
 default: all
 
@@ -65,25 +76,27 @@ all: $(BUILDDIR)manifest.ttl $(BUILDDIR)$(LV2NAME).ttl $(targets)
 lv2syms:
 	echo "_lv2_descriptor" > lv2syms
 
-$(BUILDDIR)manifest.ttl: manifest.ttl.in
+$(BUILDDIR)manifest.ttl: $(TTLDIR)manifest.ttl.in
 	@mkdir -p $(BUILDDIR)
 	sed "s/@LV2NAME@/$(LV2NAME)/;s/@LIB_EXT@/$(LIB_EXT)/" \
-	  manifest.ttl.in > $(BUILDDIR)manifest.ttl
+	  $(TTLDIR)manifest.ttl.in > $(BUILDDIR)manifest.ttl
 
-$(BUILDDIR)$(LV2NAME).ttl: $(LV2NAME).ttl.in
+$(BUILDDIR)$(LV2NAME).ttl: $(TTLDIR)$(LV2NAME).ttl.in
 	@mkdir -p $(BUILDDIR)
 	sed "s/@VERSION@/lv2:microVersion $(LV2MIC) ;lv2:minorVersion $(LV2MIN) ;/g" \
-		$(LV2NAME).ttl.in > $(BUILDDIR)$(LV2NAME).ttl
+		$(TTLDIR)$(LV2NAME).ttl.in > $(BUILDDIR)$(LV2NAME).ttl
 
-$(BUILDDIR)$(LV2NAME)$(LIB_EXT): $(LV2NAME).c
+$(BUILDDIR)$(LV2NAME)$(LIB_EXT): $(SRCDIR)$(LV2NAME).c
 	@mkdir -p $(BUILDDIR)
-	$(CC) $(CPPFLAGS) $(CFLAGS) \
-	  -o $(BUILDDIR)$(LV2NAME)$(LIB_EXT) $(LV2NAME).c \
-	  -shared $(LV2LDFLAGS) $(LDFLAGS) $(LOADLIBES)
-	$(STRIP) $(STRIPFLAGS) $(BUILDDIR)$(LV2NAME)$(LIB_EXT)
+	$(CC) $(CFLAGS) \
+		-o $(BUILDDIR)$(LV2NAME)$(LIB_EXT) $(SRCDIR)$(LV2NAME).c \
+		-shared $(LV2LDFLAGS) $(LDFLAGS) $(LOADLIBES)
 
-# install/uninstall/clean target definitions
+ifeq ($(DEBUG), 0)
+	$(STRIP) $(STRIPFLAGS) $(BUILDDIR)$(LV2NAME)$(LIB_EXT)
+endif
 
+# install/uninstall/clean/doc target definitions
 install: all
 	install -d $(DESTDIR)$(LV2DIR)/$(BUNDLE)
 	install -m644 $(BUILDDIR)$(LV2NAME)$(LIB_EXT) $(DESTDIR)$(LV2DIR)/$(BUNDLE)
@@ -99,4 +112,7 @@ clean:
 	rm -f $(BUILDDIR)manifest.ttl $(BUILDDIR)$(LV2NAME).ttl $(BUILDDIR)$(LV2NAME)$(LIB_EXT) lv2syms
 	-test -d $(BUILDDIR) && rmdir $(BUILDDIR) || true
 
-.PHONY: clean all install uninstall
+doc:
+	doxygen -s $(DOCDIR)doxygen.conf
+
+.PHONY: doc clean all install uninstall

README.md

@@ -1,34 +1,45 @@
 noise-repellent
 -------
-An lv2 plugin for broadband noise reduction.
+An lv2 plug-in for broadband noise reduction.
 
 Features
 -------
-* Spectral gating and spectral subtraction supression rule
+* Spectral gating and spectral subtraction suppression rule
 * Adaptive and manual noise thresholds estimation
-* Regulable noise floor
-* Regulable offset of thresholds to perform oversubtraction
-* Time smoothing and a postfilter for artifacts reduction
+* Adjustable noise floor
+* Adjustable offset of thresholds to perform over-subtraction
+* Time smoothing and a masking estimation to reduce artifacts
+* Basic onset detector to avoid transients suppression
 * Whitening of the noise floor to mask artifacts and to recover higher frequencies
 * Option to listen to the residual signal
 * Soft bypass
 * Noise profile saved with the session
 
 Limitations
 -------
-* The plugin will introduce latency so it's not appropriate to be used while recording
-* It was developed to be used with Ardour however it is known to work with other host
+* The plug-in will introduce latency so it's not appropriate to be used while recording (23 ms for 44.1 kHz)
+* It was developed to be used with Ardour however it is known to work with other hosts
 
 Install
 -------
-To compile and install this plugin you will need the LV2 SDK, gnu-make, a c-compiler, git, pkg-config and fftw3 library.
+To compile and install this plug-in you will need the LV2 SDK, gnu-make, a c-compiler, git, pkg-config and fftw3 library (>= 3.3.5 is recommended to avoid threading issues).
 
 ```bash
   git clone https://github.com/lucianodato/noise-repellent.git
   make
   sudo make install
 ```
-There is now an AUR package at https://aur.archlinux.org/packages/noise-repellent for Arch Users (Kindly done by CrocoDuck).
+
+There is now an AUR package at https://aur.archlinux.org/packages/noise-repellent-git for Arch Users (Kindly done by CrocoDuck).
+
+Code Documentation
+-----
+Code is documented using doxygen. To read it be sure to install doxygen in your system and run the following command
+
+```bash
+  make doc
+```
+This will generate an html folder inside doc folder. Accessing index.html you can read the documentation.
 
 Usage
 -----
@@ -38,16 +49,22 @@ Manual noise learn workflow:
 3) Once that's done turn it off and tweak parameters as you like.
 
 Adaptive noise learn workflow:
-1) Turn on Adpative mode and keep it on (preferably)
+1) Turn on Adaptive mode and keep it on (preferably)
 2) Tweak parameters
 
+What's the difference between Audacity's noise reduction tool?
+-----
+The main difference is that this plugin is coded in order to apply the effect in real time. That sounds fancy but really is a limitation. When you apply any processing offline (not in real time) you have access to all the data at once and that is a big advantage in order to use much more complex schemes for a cleaner reduction. In real time you only have access small blocks of sound at a time. So what is gained using real time processing? You have instant feedback of what you are doing (that is not the case in Audacity Noise Reduction).
+
+Ok, so in terms of interaction noise-repellent is much better but what about the internals and better yet results? Audacity uses a combination of a "second-greatest" filter to apply over-subtraction and time and frequency smoothing in order to get cleaner results. Noise-repellent uses a psycho-acoustic model based on human hearing to adaptively apply over-subtraction and time smoothing with a release envelope to avoid artifacts. Plus is has an onset detector for transient protection in percussive sounds. Alright, but how does it sounds? You'll have to try it for yourself but I haven't had the chance to encounter a case where it sounded worse yet.
 
-Control Ports explained
+Parameters explained
 -----
 * Amount of reduction: Determines how much the noise floor will be reduced.
 * Thresholds offset: Scales the noise profile learned. Greater values will reduce more noise at the expense of removing low level detail of the signal. Lower values will preserve the signal better but noise might appear.
-* Release: Timing of the reduction applied. Larger values will reduce artifacts but might blur nearby transients.
-* PF threshold: Threshold for the low SNR level detector of the postfilter. The idea behind the postfilter is to blur artifacts when only noise is present. Lower thresholds will not apply the postfilter. Higher thresholds will start to discriminate between low and high SNR moments of the track (that is between signal present and noise present chunks) and apply more filter smoothing to the lower ones.
+* Release: Timing of the reduction applied. Larger values will reduce artifacts but might blur nearby transients (only for spectral gating).
+* Masking: This enables a psycho-acoustic model that gets the masking thresholds of an estimated clean signal and adaptively scales the noise spectrum in order to avoid distortion or musical noise. Higher values will reduce more musical noise but can distort lower details of the signal. Lower values will preserve the signal more but musical noise might be heard. Value of 1 turn off this feature.
+* Transient Protection: This parameter dictates the scaling applied to the onset detection thresholding function. This means lower values will only preserve louder transients and higher values will preserve more but can reintroduce musical noise if is configured too high. The onset detector is used to detect transients and use a non smoothed suppression rule to preserve them better. Value of 1 turn off this feature.
 * Whitening: Modifies the residual noise to be more like white noise. This takes into account that our ears do well discriminating sounds in white noise versus colored noise. Higher values will brighten the residual noise and will mask high frequency artifacts.
 * Learn noise profile: To manually learn the noise profile.
 * Adaptive noise learn: To change the noise profile dynamically in time. This enables the automatic estimation of noise thresholds.
@@ -58,21 +75,21 @@ Advice for better reduction
 -----
 General noise reduction advice
 * Try to reduce and not remove entirely the noise. It will sound better.
-* Gentler settings with multiple intances of the plugin will probably sound better than too much reduction with one intance. Of course for every intance the noise should be re-learned again.
+* Gentler settings with multiple instance of the plug-in will probably sound better than too much reduction with one instance. Of course for every instance the noise should be re-learned again.
 * If the noise varies to much from one section to other apply different reduction for each part.
 * Always remember to listen to the residual signal to make sure that you are not distorting the signal too much.
-* Start with the reduction at 0 dB and then decrease it until you hear artifacts then tune the paremeters to get rid of them without distorting the signal.
+* Start with the reduction at 0 dB and then decrease it until you hear artifacts then tune the parameters to get rid of them without distorting the signal.
+* It might help using an spectrogram analysis to help you notice what you are doing. This can be easily done by using a-Inline Spectrogram in Ardour or the spectrogram view in audacity or sonic visualizer
 
 For adaptive Reduction:
 * Adaptive mode should be used only with voice tracks because the algorithm for noise estimation is tuned for that use.
-* It's recommended to play with thresholds offset because those are estimated continuosly and the algorithm used for that tends to overestimate them.
-* Shorter release will preserve higher frequencies better, but make sure to not set it so low that artifacts start to creep in.
-* Set PF threshold to -60 dB to deactivate posffiltering. Postfilering will not do much when noise thresholds are being estimated continuosly.
-* If the track you are processing does not have a long section of noise before the wanted signal starts cut some noise from an inbetween section and extend the beggining a bit. This is to take into account the time that takes the algorithm to learn the noise. Alternatively you can learn the noise by using one section of the track and then turning off the adaptive mode so a fixed noise profile is used. This will not adapt in time but will give you something to work with.
+* It's recommended to play with thresholds offset because those are estimated continuously and the algorithm used for that tends sometimes to overestimate them.
+* Release won't work at all in this version. To reduce more or less use threshold offset
+* If the track you are processing does not have a long section of noise before the wanted signal starts cut some noise from an in-between section and extend the beginning a bit. This is to take into account the time that takes the algorithm to learn the noise. Alternatively you can learn the noise profile by using one section of the track and then turning off the adaptive mode so a fixed noise profile is used. This will not adapt in time but will give you something to work with.
 
 For manual reduction:
 * You can use adaptive mode to estimate noise thresholds when there is no section in the track that contains only noise. It should be used the same way you would use the manual learn.
-* If noise floor change a bit over time it might be useful to use higher thresholds offset.
-* Make sure that the section you select to learn the noise profile is noise only (without breaths or sustained notes or anything but noise)
-* The longer the section you select to learn the noise profile the better the reduction will sound.
-* It's better to start reducing artifacts by using a longer release until some of the original signal is starting to appear in the residual noise. Reduce the release a bit and then increase the postfilter threshold for even more artifacts reduction. Of course check the residual noise for any distortion.
+* If noise floor changes a bit over time it might be useful to use higher thresholds offset.
+* Make sure that the section you select to learn the noise profile is noise only (no breaths or sustained notes or anything but noise)
+* The longer the section you select to learn the noise the better the reduction will sound.
+* The best way to reduce artifacts is to use a combination of masking, release and transient protection controls. Masking will reduce musical noise and at the same time it will preserve the wanted signal but too much will start to distort it. Release can reduce musical noise significantly but too much can blur transients away. To avoid this you can increase transient preservation until you find those transients less distorted. If you are not perceiving what you are doing, listen to the residual signal and increase to a higher value. Each of this controls work independently be sure to try the smallest amount of each one just to avoid artifacts. This will lead to a better reduction.

doc/doxygen.conf

@@ -0,0 +1,7 @@
+PROJECT_NAME = "Noise Repellent"
+PROJECT_BRIEF = "An lv2 plugin for broadband noise reduction"
+OUTPUT_DIRECTORY = "doc"
+INPUT = "src"
+EXTRACT_STATIC = YES
+GENERATE_LATEX = NO
+OPTIMIZE_OUTPUT_FOR_C = YES