marty-oehme/bemoji

Emoji picker that remembers your favorites, with support for bemenu/wofi/rofi/dmenu and wayland/X11.

bemoji ❤️ - Quickly ⛏️ your 🌟

Emoji picker with support for bemenu/wofi/rofi/dmenu and wayland/X11.

Will remember your favorite emojis and give you quick access.

📁 Installation

Dependencies

• One of bemenu, wofi, rofi, dmenu, ilia, fuzzel or supplying your own picker.
• One of wl-copy, xclip, xsel or supplying your own clipboard tool.
• One of wtype, xdotool or supplying your own typing tool.
• sed, grep, cut, sort, uniq, tr, curl if using the download functionality.

To see how to substitute the default choices with your own tools, see Options below.

Manual

Option 1. Clone the repository and put the executable somewhere in your path:

git clone <INSERT-REPOSITORY>
chmod +x bemoji/bemoji
mv bemoji/bemoji /usr/local/bin/bemoji
rm -r bemoji

Option 2. Clone the repository and link the executable to your path:

git clone <INSERT-REPOSITORY>
chmod +x bemoji/bemoji
ln -s bemoji/bemoji /usr/local/bin/bemoji

Arch Linux

On Arch Linux, bemoji has been packaged for the AUR so it can be installed manually from here or easily with your preferred AUR helper, e.g.:

paru -S bemoji # or bemoji-git

💿 Usage

Simply execute bemoji without any options to set up the default emoji database and let you quickly pick an emoji. It will be copied to your clipboard for you to paste anywhere. If you execute bemoji -t it will directly type your emoji directly into whatever application is in focus.

When the emoji list is open you can always press Alt+1 to send the selected emoji to clipboard and Alt+2 to type the selected emoji, regardless of what the default action is set to. (Currently works in bemenu and rofi.)

You can also map the picker to a key combination for quick access, e.g.

In swaywm, put the following in ~/.config/sway/config:

bindsym Mod4+Shift+e exec bemoji -t

For i3, put the same into ~/.config/i3/config:

bindsym Mod4+Shift+e exec bemoji -t

For riverwm, put the following in ~/.config/river/init:

riverctl map normal Mod4+Shift E spawn "bemoji -t"

In sxhkd, put the following into ~/.config/sxhkd/sxhkdrc:

super + Shift + e
    bemoji -t

And you can easily type any emoji with the help of Super+Shift+E.

🧰 Options

bemoji comes with a couple of options to specify actions, emoji libraries and directories being used.

Adding your own emoji

Simply put your own emoji list into the bemoji data directory. By default, the directory will be at your $XDG_DATA_HOME/bemoji location - most likely this is ~/.local/share/bemoji.

Add any number of .txt files containing additional emoji to this directory:

🫦 Biting lip
🫶 Heart Hands

The lists need to have the format 🙂 description of emoji with a whitespace separating the emoji and its description. The description can have as many words and whitespaces as you want.

Ignoring the most recent emoji

By default, bemoji will sort the list it displays by your most frequently and most recently used emoji. To disable this behavior, execute bemoji like the following:

bemoji --hist-limit 0

This will stop bemoji from adding recently used emoji before displaying the list.

You can also stop bemoji from adding any emoji to your history in the first place:

bemoji --private

This will not add any of the emoji you pick to your recent emojis. Put both together to completely ignore the recent emoji feature of the program (these are the equivalent short versions of the options above):

bemoji -p -P0

Like this, you'll be hiding any recent personal emoji and no one will know that you always type 👄🍆💦.

To limit the number of your recently used emoji that are shown without hiding them completely simply increase the number to however many you wish to display. For example, to display only the top 4 recently used emoji:

bemoji --hist-limit 4

The recent list will also contain emoji that are not usually on your lists, so kept in single-use lists for example. If you don't wish those to show up, make use of these options.

Setting custom directories and editing history

By default bemoji stores your recent history in $XDG_STATE_HOME/bemoji-history.txt, so most often in ~/.local/state/bemoji-history.txt

You can edit this file in any text editor to change your recent history, removing, adding or changing the emoji appearing there.

You can overwrite the directories bemoji uses for its emoji lists and history files with the following two environment variables:

BEMOJI_DB_LOCATION=/path/to/my/emoji/directory
BEMOJI_HISTORY_LOCATION=/path/to/my/state/directory

There are no equivalent commandline arguments to overwrite these two settings.

Display one custom emoji list

A custom emoji list can be supplied as commandline argument -f or BEMOJI_CUSTOM_LIST environment variable.

bemoji --file path/to/my/list.txt

The list will override the normally presented emoji, so that only the custom list and recent emoji will be displayed. To display only the emoji list passed in, pass an extra -P flag to bemoji.

The path can also be a weblink which bemoji will download and use:

bemoji -f "https://raw.githubusercontent.com/jchook/emoji-menu/master/data/emojis.txt"

Download additional emoji sets

bemoji automatically downloads an emoji list for you to use on first invocation. By default, it only downloads emoji, though you can have it download math symbols and nerdfont icons as well. To download additional sets, execute bemoji like the following:

bemoji --download all

This will download all default sets bemoji knows - which is currently the default emoji list, nerd font icons, and a long list of math symbols. Other valid options for this setting are emoji, math, nerd, none.

bemoji -D "math emoji nerd"

The above command is equivalent to the previous all as you can mention multiple sets you want downloaded.

If set to none and no files are in the emoji directory, bemoji will complain and not show anything.

Do not skip to new line after output

By default, bemoji will craft the final output using a typical echo call for anything it prints directly.

That means, it will also contain a final newline character. So, for example it would technically output 🦊\n for the fox emoji, which skips to a new line in most circumstances.

If you wish to prevent this character in the final output, use:

bemoji -n

Using this option will suppress the newline character and only print 🦊 as its output.

Using a custom tool for picking, clipping, typing

If you want to replace one of the default supported tools with your own you can do this through environment variables:

BEMOJI_PICKER_CMD="path/to/your/picker-tool"
BEMOJI_CLIP_CMD="path/to/your/clipboard/tool"
BEMOJI_TYPE_CMD="path/to/your/xdotool"

The candidate list (in the case of picker tool) or the picked selection are passed to the tools through stdin.

For example, to manually invoke fuzzel with no extra options as the picker for bemoji you would use:

BEMOJI_PICKER_CMD="fuzzel -d" bemoji

This is somewhat experimental still and you'll have to see how well it works for you. The setting can not be changed through the commandline alone.

Execute a custom command with my emoji

You can execute bemoji with the -e flag with which you tell it not to do anything but echo out the chosen emoji.

This can be very useful for creating your own little script with it:

bemoji --echo | cat <(echo -n "https://emojipedia.org/") - | xargs xdg-open

This snippet will open a wiki page for the picked emoji in your browser.

Of course, there are many more possibilities. This is just an example to show how the echo mode works.

A list of all environment variables

What follows is a list of all environment variables bemoji understands, with their default settings

BEMOJI_DB_LOCATION="$XDG_DATA_HOME/bemoji" # where the emoji lists reside
BEMOJI_HISTORY_LOCATION="$XDG_STATE_HOME" # where the state file resides
BEMOJI_CUSTOM_LIST="" # the custom emoji list to display
BEMOJI_DOWNLOAD_LIST="" # the default emoji lists to download to database
BEMOJI_DEFAULT_COMMAND="" # which command to invoke by default
BEMOJI_PICKER_CMD="bemenu" # which picker tool to use
BEMOJI_CLIP_CMD="wl-copy" # which clipboard tool to use
BEMOJI_TYPE_CMD="wtype" # which typing tool to use (ydotool will NOT work)
BEMOJI_PRIVATE_MODE=false # whether to save new entries
BEMOJI_LIMIT_RECENT="" # whether to display recent entries
BEMOJI_ECHO_NEWLINE=true # whether to end the output with a newline character

🤗 Issues

Thanks for checking this program out! ❤

If there are any problems, don't hesitate to open an issue.

If you have an idea or improvement, don't hesitate to open a merge request!

Running tests

This project makes use of bash-bats (community fork) to test some of its functionality.

To run the tests locally:

git submodule init
git submodule update
./test/bats/bin/bats test

I would suggest running the test suite in docker instead, just to minimize the possibility of something going awry and borking up your local file system. To run the tests in a docker suite, execute docker run --rm -it -v "$PWD:/code" bats/bats:latest /code/test after initializing the git submodules as listed above.

bemoji's Issues

[Feature] Unicode addition in the db

A new argument flag that gives the user a choice to download Unicode characters dictionary from the source (This one can be used).

Having emoji and Unicode together can have conflict so we can have different search patterns to make it easier

e.g normal search results in emoji on top
searching with u:<name> should result in Unicode on top
This can be achieved by adding u: at the start of the Unicode description .txt and for bemenu we can sed it and remove it when the user invokes it.

Custom typing tool usage

I'm confused about how custom typing tool selection is supposed to work at https://github.com/marty-oehme/bemoji/blob/main/bemoji#L171.

I'm using autotype for typing, which supports both stdin and the first argument selection.

The workaround is to let bemoji echo output and pipe it to the tool, but that defeats the whole point of supporting custom typing tooling selection that's built in:

$ bemoji -ne | autotype

[Feature] allow setting skin tone

If your search matches an emoji with skin tones, your results can be spammed with all the skin tone variations of one or two emojis rather than showing you 10 or more different emojis. The result you are looking for may be pushed off the first page by all the skin tone variations.

For example, if you search for red, there are 6 entries for "man with red hair", 6 entries for "woman with red hair" and 6 more for "person with red hair".

If a skin tone could be set on the CLI, there could be only 3 results instead of 18:

bemoji --skin-tone="medium"

• man: medium skin tone, red hair
• woman: medium skin tone, red hair
• person: medium skin tone, red hair

Or, perhaps even cleaner is not mention the skin tone at all when it's given on the CLI, so the results could be simply:

• man: red hair
• woman: red hair
• person: red hair

In this case "man: red hair" would actually show and select "man: medium skin tone, red hair" instead of the generic "man: red hair" emoji.

Improve custom BEMOJI_TYPE_CMD documentation

Running from the terminal just gives this output. The emoji selector does appear.

bemoji -t
Usage: wtype <text-to-type>

Using keyboard shortcut it shows the emoji selector but then types nothing.

I'm using rofi as my picker.

Not sure when it stopped working but I know it worked a couple of weeks ago.

Where to set the environment variables?

Probably a stupid question, but where do I define the environment variables such as BEMOJI_PICKER_CMD? Is it a config file stored somewhere?

It looks like I should setting the BEMOJI_PICKER_CMD to "fuzzel", but I don't know where.

A problem with typing `--delay30` string by xdotool

Hi Marty!

I use bemoji -t with instant typing parameter to paste an emoji character into an active input. I've discovered that xdotool also typing a following string: --delay30:

So I decided to fix it, here is my PR: #2

Return 1 if cancelled

This would be helpful for scripting purposes when you abandon selection on Esc. bemenu does so.

Release with fuzzel

Could we get an official release with the new fuzzel picker included? That would be awesome 😺

Make use of new XDG spec for history state

There's a new directory in (XDG) town and it looks like a perfect fit for the emoji history file: XDG_STATE_HOME.

It is intended for basically exactly this:

$XDG_STATE_HOME defines the base directory relative to which user-specific state files should be stored. If $XDG_STATE_HOME is either not set or empty, a default equal to $HOME/.local/state should be used.

More here: https://teddit.net/r/linux/comments/ny34vs/new_xdg_state_home_in_xdg_base_directory_spec/
and here: https://wiki.debian.org/XDGBaseDirectorySpecification#state

One consideration is if it should, by default, still fall back to the old XDG_DATA_HOME directory or break with it and follow the new XDG spec more closely.

Changing picker to fuzzel not working

I have changed the picker using the env like this into my .bashrc
export BEMOJI_PICKER_CMD=fuzzel

But now when I try to execute bemoji, the emojis are not being displayed, instead the default fuzzel with the .desktop icons appears

Bemenu Args

How can i pass bemenu arguments?

Bump to Emoji 15.0

I miss the 🪿.

And maybe it makes sense to put URLs for both emojis and math symbols at the top as variables, so all hardcoded values are clearly visible and not buried in the code.

Allow list downloading when lists already exist

Currently, once there are lists existing in the bemoji data directory, the program will never download additional lists.
This holds, even if you specifically supply the program with the -D option which tells the program which lists you would like downloaded.

That means, for most people, after running the program once they will not be able to download additional lists and the -D option becomes largely useless.

What would improve usability instead, I believe, would be to change -D into a command switch, akin to -t, -c and -e currently, which starts a download of all lists supplied - no matter the current state of the data directory.

This will allow downloading additional lists at any point and makes the -D switch a little less useless after the initial run.

First entry in picker is "No suitable picker tool found."

Having bemenu installed and in my path, running the command bemoji -n, I get "No suitable picker tool found." as the first entry in the picker. Except for that, it works like a charm. All the other entries are actual emoji, and copying them works.

How to make it work with Clipman

Hi,

How can I make it work with the Clipman clipboard https://docs.xfce.org/panel-plugins/xfce4-clipman-plugin/start ?

Thank you.

Copy and type

How can i copy and type the emoji at the same time ?

`noto-fonts-emoji` support ?

I'm not sure if this is only my setup issue but, bemoji outputs empty list. I already have noto-fonts-emoji installed on my arch. I'm using fuzzel btw. Should I do something more ?

LOGS

$[~]$ echo $BEMOJI_PICKER_CMD 
fuzzel --dmenu
$[~]$ bemoji 
info: main.c:1154: version: 1.9.2 +cairo +png +svg(nanosvg) -assertions
info: config.c:1475: loading configuration from /etc/xdg/fuzzel/fuzzel.ini
info: wayland.c:2018: HDMI-A-1: 1920x1080+0x0@60Hz DELL S2216H 21.68" scale=1 PPI=106x108 (physical) PPI=106x108 (logical), DPI=101.60
info: fcft.c:338: fcft: 3.1.6 +graphemes +runs +svg(nanosvg) -assertions
info: fcft.c:377: fontconfig: 2.14.2, freetype: 2.13.2, harfbuzz: 8.3.0, utf8proc: 2.9.0 (Unicode 15.1.0)
info: fcft.c:838: /usr/share/fonts/TTF/iosevka-regular.ttc: size=12.00pt/17px, dpi=101.60
info: main.c:455: theme: hicolor

My fonts.conf

<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd">
<fontconfig>

  <!-- settings go here -->

  <!-- Fallback fonts preference order -->
  <alias>
    <family>sans-serif</family>
    <prefer>
      <family>Noto Sans</family>
      <family>Open Sans</family>
      <family>Droid Sans</family>
      <family>Roboto</family>
    </prefer>
  </alias>
  <alias>
    <family>serif</family>
    <prefer>
      <family>Noto Serif</family>
      <family>Droid Serif</family>
      <family>Roboto Slab</family>
    </prefer>
  </alias>
  <alias>
    <family>monospace</family>
    <prefer>
	  <family>Iosevka</family>
	  <family>Noto Sans Mono</family>
	  <family>Droid Sans Mono</family>
	  <family>Roboto Mono</family>
    </prefer>
  </alias>

</fontconfig>

Fuzzel issue tracker here

Visual artifacts

The bemoji window also flickers but that apparently isn't captured by OBS Studio:

Consider renaming the project to "bashmoji"

There is another more populate software project named "bemoji" , that fills up most of the search results of the first couple pages when searching exactly for the name:

https://www.google.com/search?hl=en&q=bemoji

Also consider adding some Github tags to make it easier to find, as the dmenu-emoji project did. This project generally works great, but is a little hard to find.

[Feature] Prompt to add Nerd font

As the emoji Db is mere simple .txt
we can prompt the user at first start if he wants to have the Nerd Font Cheat Sheet database appended to it to have access to much more glyphs.

Ability to limit maximum recent entries

Currently, the complete history of emoji (though only unique entries) is displayed whenever the program is called up with history function.

This is no problem when only the default emoji set is used since matching emoji are removed from the output list.

But if multiple changing and unique emoji sets are used, more and more emoji from those will pile up which might prove to be a problem.

Add AUR package to installation methods

Somebody nicely packaged the project for Archlinux systems in the AUR.

The readme should indicate this easy method of installation.

Extra new line is always added with Wayland clipboard

When you select a emoji it for some reason adds a new line annoyingly like so

💔

Not sure if this only effects Wayland or not or what, but also would prefer if it just inputted the emoji which is possible pretty sure

Allow user choice of (in-built) picker tool

Currently we allow the user to set a completely custom picker tool (via envvar BEMOJI_PICKER_CMD) or relying on the tool selecting a picker for them from an in-built list.
There is no in-between option for a user to select their picker from the built-in list.

If the BEMOJI_PICKER_CMD first goes through the existing default pickers and chooses the right one and then simply uses the input as-is we could satisfy both conditions.

I.e. BEMOJI_PICKER_CMD=rofi would select rofi from the default, while BEMOJI_PICKER_CMD="mypicker -mode dmenu" directly use the option as command. For that matter, BEMOJI_PICKER_CMD="rofi -dmenu -p EMOJI" would also directly work as command.

While doing this it might make sense to think about allowing this option to be set through a command line option as well.