*keysound.txt*	For Vim version 9.0	Last change: 2023 Oct 23

	                            /`*_ ~
	                            /    `-_ ~
	                 _.,  _.   /        `-_ ~
	             _,-` __`-_ `-/            `-_ ~
	          ,-  .,~`  /  `-/               .` ~
	         :_ -`     "    /`-@             / ~
	                  /`\  ;    `-_         / ~
	               |-`.. `-\  |    `-_     / `-_ ~
	            _-`  `_.`\  `-_ |;\   @-_ / `-_/ ~
	           -  .__.,,;___o  `-_|      /`-__-_ ~
	          - 1`-_ .~--` _~` o   `-_   ;   `   - ~
	        .`Q W 2 `-_ `,`. /- - o   `-_\  `     ` ~
	       - A S  E  3 `-_  . / .|   _ ..`-_;     : ~
	    _-` Z X  D F R T 4`-_  ;  ;   `_ `_-`.-_,` ~
	 .-`--_     C   G   Y  5 `-_ i    _-`    ; ~
	:  `-_//`-_   V  H J U I 6  `-_.-`       * ~
	-_    `-_  `-_    B N K L O 7 -          : ~
	  `-_    `-_  `-_    M . ; P .`      es  ; ~
	     `-_    `-_  `-_     ,  -           _` ~
	        `-_    `-_ /     -`         _-` ~
	           `-_    `-_/-_`        _-` ~
	              `-_    `-.      _-` ~
	                 `-_   .   .-` ~
	                    `-_:_-`  Dedicated to the memory of Bram~

	Author:  Lifepillar <https://github.com/lifepillar>
	License: Same terms as Vim itself (see |license|)
==============================================================================
KEYSOUND					*keysound*

KeySound adds typewriter sounds to Vim in |Insert-mode|. It requires Vim 9.0
or later compiled with |+sound|.

						*:KeySoundDebug*
:KeySoundDebug		Print debugging information in a dialog.

						*:KeySoundOff*
:KeySoundOff		Turn off typewriter sounds.

						*:KeySoundOn*
:KeySoundOn		Activate typewriter sounds.

						*:KeySoundToggle*
:KeySoundToggle		Toggle typewriter sounds.

By default, KeySound plays a sound for each key triggered by |InsertCharPre|.
It also plays a "carriage return" sound when pressing |<Enter>|.

						*g:keysound*
A |dict| to configure which sounds should be played for each key press. This
is the default configuration:
>
	g:keysound = {
	  'default': ['keyany.wav'],
	    "\<cr>": ['keyenter.wav'],
	}
<
Users may define `g:keysound` in their |vimrc| to extend or override the
default configuration. The dictionary maps keys or events to lists of sound
files. The special `'default'` entry is used for keys that are not explicitly
defined in `g:keysound`. Keys may also be the names of |autocmd-events|.

When a key or event is associated with more than one sound, a sound is chosen
randomly each time that key is pressed or that event is triggered. To suppress
a sound for a specific key, map it to an empty list or use |null_string| or an
empty string. For example:
>
	g:keysound = {
	    "\<bs>":       ['key001.wav'],
	    'f':           ['key002.wav'],
	    'q':           ['key003.wav', 'key004.wav', ''],
	    'j':           [],
	    'k':           [null_string],
	    'default':     ['key005.wav'],
	    'InsertLeave': ['ding000.wav'],
	}
<
With the configuration above:

- pressing Backspace will play key001.wav;
- pressing f will play key002.wav;
- pressing q will randomly play one of key003.wav or key004.wav or no sound.
- pressing j will not play any sound;
- pressing k will also not play any sound;
- any other key triggering |InsertCharPre| will play key5.wav;
- pressing Enter will play the default sound for carriage return;
- the remaining keys will not play any sound;
- finally, ding000.wav will be played each time Insert mode is exited.

Keys that do not trigger |InsertCharPre|, such as |<Enter>|, |backspace|,
etc., must not be mapped for KeySound to be able to configure them (see
|key-mapping|), because KeySound will need to map those keys. If a mapping
already exists, KeySound will not overwrite it: you will need to set up the
mappings yourself.

The available sound files are located inside the `sounds` folder of the
plugin. You may add your own sounds there. The supported formats vary with the
platform, although probably WAV is the most compatible across libraries. Other
formats that may be supported by your platform include MP3 and Ogg/Vorbis.

						*g:keysound_toggle_event_sounds*
When set to false, sounds associated to events are played even when KeySound
is off. That is, only keyboard sounds are toggled.
>
	g:keysound_toggle_event_sounds = true
<
						*g:keysound_throttle*
Maximum number of simultaneous sounds to play. When typing fast and this
threshold is exceeded, sounds are skipped for additional key presses as long
as the number of simultaneously playing sounds is higher that the threshold.
The threshold must be a positive value.
>
	g:keysound_throttle = 20
<
PlaySoundFor({key} [, {flag}])			*keysound.PlaySoundFor()*
		Plays the sound corresponding to the given {key}. The sound is
		played only if KeySound is on. Returns {key} unless {flag} is
		set to false, in which case returns an empty string.
		This function may be used in user mappings to enable sounds
		for keys that are already mapped. See an example in the
		section below.

==============================================================================
CONFLICTING MAPPINGS				*keysound-conflicts*

If a key is already mapped by the user or by another plugin, it will play no
sound even if it is configured in |g:keysound|, because KeySound never
overwrites existing mappings: it wouldn't be polite. Make sure KeySound is on,
and check for conflicts with |:KeySoundDebug|.

You have to resolve such conflicts yourself, because how to solve them very
much depends on how the mappings were defined.

For example, if you use Auto Pairs, which defines mappings for <cr>, <bs>, and
<space> among the rest, you may add this to your |vimrc|:
>
	vim9script

	import '/path/to/keysound/autoload/keysound.vim'

	g:AutoPairsMapCR = 0
	g:AutoPairsMapBS = 0

	inoremap <expr> <plug>keysoundCR keysound.PlaySoundFor("\<cr>")
	inoremap <expr> <plug>keysoundBS keysound.PlaySoundFor("\<bs>", false)
	inoremap <expr> <plug>autopairsBS g:AutoPairsDelete()

	imap <cr> <plug>keysoundCR<plug>AutoPairsReturn
	imap <bs> <plug>autopairsBS<plug>keysoundBS

	# Silence some characters to avoid double sounds:
	g:keysound = {
	  "\<space>": [],
	         '[': [],
	         '{': [],
	       # etc.
	}
<
The above is for a |vimrc| written in Vim 9 script. If your |vimrc| is written
in legacy Vim script, the equivalent snippet looks as follows:
>
	let g:AutoPairsMapCR = 0
	let g:AutoPairsMapBS = 0

	inoremap <expr> <plug>keysoundCR keysound#PlaySoundFor("\<cr>")
	inoremap <expr> <plug>keysoundBS keysound#PlaySoundFor("\<bs>", 0)
	inoremap <expr> <plug>autopairsBS AutoPairsDelete()

	imap <cr> <plug>keysoundCR<plug>AutoPairsReturn
	imap <bs> <plug>autopairsBS<plug>keysoundBS

	let g:keysound {
	  \ "\<space": [],
	  \       '[': [],
	  \       '{': [],
	  \       etc.
	  \ }
<
==============================================================================
ACKNOWLEDGMENTS					*keysound-credits*

https://gottcode.org/focuswriter/
The default sounds are from FocusWriter, a beautiful distraction-free editor
supporting RTF and ODT formats, besides plain text files. FocusWriter and its
sound files are distributed under the GPLv3.

https://github.com/AndrewRadev/typewriter.vim
typewriter.vim is a plugin similar to KeySound, but written in legacy Vim
script, from which I borrowed the idea of throttling the sounds.

https://asciiart.website/index.php?art=objects/typewriter
Where the ASCII art typewriter in this help file comes from.

 vim:tw=78:ts=8:noet:ft=help:norl:
