JOME(1)

NAME
jome - a keyboard centric desktop emoji picker

SYNOPSIS

jome [-f cp [-p PREFIX]] [-n] [-V] [-t (L | ML | M | MD | D)]
     [-c CMD] [-b] [-q | -s NAME]
     [-d] [-C] [-L] [-R] [-k]
     [-w (16 | 24 | 32 | 40 | 48)] [-P] [-H COUNT]

DESCRIPTION

jome (joh·mee) is a keyboard centric emoji picker desktop application.

jome’s sole purpose is to help you pick an emoji. In other words, it doesn’t really care what you do with the chosen emoji afterwards: you can leverage tools such as xdotool(1) to “type” it or xsel(1) to copy it to the clipboard. See the “Type the accepted emoji” section below and the -c option for a starting point.

When you accept an emoji (with the keyboard or with the mouse), jome prints the UTF-8 emoji or the Unicode codepoints (see the -f option), with an optional prefix (see the -p option) for each codepoint, to the standard output.

Additionally, jome can:

    • Copy the UTF-8 emoji or the Unicode codepoints to the clipboard.

    See the -b option.

    • Execute a custom command which sends the UTF-8 emoji or the Unicode codepoints, with an optional prefix for each codepoint, as its last argument(s).

    See the -c option.

    • Send the UTF-8 emoji or the Unicode codepoints, with an optional prefix for each codepoint, in response to a client which requested picking an emoji.

    See the “Server mode” section below.

If you close the window (you can press Escape or Ctrl+C to do this), then jome prints nothing to the standard output, executes nothing, and exits with status 1.

If you don’t start jome in server mode (-s option) and you don’t specify the -q option, then jome immediately exits with status 0 after you accept an emoji or close the window.

  Graphical interface

There are four sections:

Find box (top)
    Input box where you can type a query to find emojis.

Emoji grid
    All emojis (with an empty find box) or find results.

    When there’s at least one emoji, there’s always a selected emoji with a square box around it.

    Click an emoji to accept it. Press Shift when clicking to not print VS-16 codepoints (see the -V option).

    Hover an emoji to update the bottom emoji info text temporarily.

    Make the background behind emojis dark with the -d option.

    Hide the category labels with the -L option.

    Hide the “Recent” category with the -R option.

Category list (right)
    List of available categories.

    When all emojis are viewed (the find box is empty), click a category name to scroll to this emoji category.

    The first category, “Recent”, is a special category with the recently accepted emojis.

    Override the maximum number of recently accepted emojis with the -H option.

    Hide the “Recent” category with the -R option.

    Hide the whole category list with the -C option.

Emoji info text (bottom)
    Name, Unicode codepoints, Emoji standard version, and keywords of the selected or hovered emoji.

    Hide the keyword list with the -k option.

  Find emojis

The power of jome is its find box (top).

When you launch jome, the find box is focused, and it should stay focused unless you browse emojis manually with the intention of accepting one with the mouse.

The format of a query is one of:

    • TERMS

    • CAT/

    • CAT/TERMS

    • CODEPOINT

    • CAT/CODEPOINT

where:

CAT
    Partial name of categories in which to find.

TERMS
    Space-separated list of search terms.

    For an emoji to be part of the results, its name and keywords must contain ALL the searched terms.

CODEPOINT
    A single Unicode codepoint using the standard U+ABCD notation.

Everything is case-insensitive.

  Select and accept an emoji

To select an emoji, use the following keys:

←, →, ↑, ↓
    Go left/right/up/down.

Ctrl+←, Ctrl+→
    Go left/right five emojis.

Page ↑, Page ↓
    Go up/down ten rows.

Home
    Go to the first emoji.

End
    Go to the last emoji.

To accept the selected emoji, press:

Enter
    Accept the selected emoji with, if applicable:

    Without the -t option
        No skin tone (“yellow”).

    With the -t option
        The default skin tone (value of -t).

Shift+Enter
    Like Enter, but do not print VS-16 codepoints.

    See the -V option option.

F1 to F5
    If the selected emoji supports skin tones, accept the selected emoji with a light, medium-light, medium, medium-dark, or dark skin tone, overriding the -t option (if any).

Shift+F1 to Shift+F5
    Like F1 to F5, but do not print VS-16 codepoints.

    See the -V option option.

To cancel, press Escape or Ctrl+C, or close the window.

  Go to Emojipedia page

To go to the page of the selected emoji, press F12.

To go to the Emojipedia page of any emoji with the mouse, right-click it and click “Go to Emojipedia page”.

  User-defined emoji keywords

You can either replace or augment the built-in list of keywords which jome searches when you find emojis.

To set user-defined keywords, create an emojis.json file within ~/.config/jome/.

emojis.json must contain a JSON object where keys are emojis and values are objects. Each value may contain one of:

keywords
    An array of keywords which replaces the built-in keywords entirely for this emoji.

extra-keywords
    An array of keywords which augments either the built-in keywords or the keywords of the keywords entry for this emoji.

Example:

    {
      "🍁": {
        "extra-keywords": ["canada", "laurentides"]
      },
      "😃": {
        "keywords": ["yay", "hourra"]
      },
      "🚬": {
        "extra-keywords": ["claude poirier"]
      },
      "🫚": {
        "extra-keywords": ["canada dry", "martin deschamps"]
      }
    }

  Server mode

jome features a server mode to avoid creating a process (a Qt window can be quite long to create) every time you need to pick an emoji. With this mode, you can view the jome window instantaneously.

To start jome in server mode, use the -s option to specify the server name:

    $ jome -s mein-server

This creates a local server named mein-server. On Unix, it creates the socket file /tmp/mein-server.

    Important

    On Unix, the server mode won’t work if the socket file already exists. Remove the file before you start jome in server mode:

        $ rm -f /tmp/mein-server
        $ jome -s mein-server

When jome starts in server mode, it doesn’t show its window. Instead, it waits for a command sent by the client, jome-ctl(1). To show the window:

    $ jome-ctl mein-server

When you accept an emoji, jome-ctl(1) prints what jome also prints to the standard output and quits with exit code 0. Therefore, the options passed to jome(1) control the output format of jome-ctl(1).

If you cancel jome (press Escape or Ctrl+C, or close the window), jome-ctl(1) prints nothing and returns with exit code 1.

In server mode, jome doesn’t quit once you accept an emoji or cancel: it hides the window and keeps listening. To make it quits gracefully, which also removes the socket file:

    $ jome-ctl mein-server quit

You don’t need to use what jome-ctl(1) prints to the standard output. You can use jome in server mode with the -c option to make jome execute a command itself. For example:

    $ rm -f /tmp/mein-server
    $ jome -s mein-server -c 'xdotool type'

Then, bind a keyboard shortcut to:

    $ jome-ctl mein-server

  Type the accepted emoji

Here are Bash scripts to type the accepted emoji with xdotool(1).

Direct mode

    With xdotool key

            #!/usr/bin/bash

            codepoints=$(jome -f cp -p U)

            if (($? != 0)); then
                exit 1
            fi

            xdotool key --delay 20 "$codepoints"

    With xdotool type

            #!/usr/bin/bash

            emoji=$(jome)

            if (($? != 0)); then
                exit 1
            fi

            xdotool type "$emoji"

Server mode

    With xdotool key

            #!/usr/bin/bash

            socket_name=jome.socket.$(id -u)

            if [[ ! -e "/tmp/$socket_name" ]]; then
                jome -s "$socket_name" -n -w48 -f cp -p U & disown

                until [[ -e "/tmp/$socket_name" ]]; do
                    sleep .1
                done
            fi

            codepoints=$(jome-ctl "$socket_name")

            if (($? == 0)); then
                sleep .02
                xdotool key --delay 20 "$codepoints"
            fi

    With xdotool type

            #!/usr/bin/bash

            socket_name=jome.socket.$(id -u)

            if [[ ! -e "/tmp/$socket_name" ]]; then
                jome -s "$socket_name" -n -w48 & disown

                until [[ -e "/tmp/$socket_name" ]]; do
                    sleep .1
                done
            fi

            emoji=$(jome-ctl "$socket_name")

            if (($? == 0)); then
                sleep .02
                xdotool type "$emoji"
            fi

OPTIONS

  Output

-f FMT
    Set the output format to FMT:

    utf-8 (default)
        UTF-8 emoji.

    cp
        Space-separated Unicode codepoints (hexadecimal).

        Example: 1f645 200d 2642 fe0f

        Prepend a prefix to each codepoint with the -p option.

-p PREFIX
    Set the prefix to be prepended to each Unicode codepoint with -f cp.

    For example, with -f cp and -p U+:

        U+1f645 U+200d U+2642 U+fe0f

-n
    Do not print a newline after printing the emoji or codepoints.

-V
    Do not print (VS-16) codepoints.

    VS-16 is a suffix codepoint which specifies that the preceding character should be displayed with emoji presentation. For example, ♥ (which predates Unicode emojis) followed with VS-16 becomes a red heart.

    There are applications/fonts which don’t like VS-16.

-t TONE
    Set the default skin tone to TONE instead of none:

    L
        Light.

    ML
        Medium-light.

    M
        Medium.

    MD
        Medium-dark.

    D
        Dark.

    The F1 to F5 keys still acept an emoji with a specific skin tone.

  Action

-c CMD
    When you accept an emoji, execute the command CMD 20 ms after closing the jome window.

    jome interprets CMD like a shell does, so you can have arguments too.

    CMD receives the UTF-8 emoji or the Unicode codepoints (depending on the -f option) with their optional prefix as its last argument(s).

    Examples with xdotool:

        $ jome -c 'xdotool type'
        $ jome -f cp -p U -c 'xdotool key --delay 20'

-b
    When you accept an emoji, copy the UTF-8 emoji or the Unicode codepoints (depending on the -f option) to the clipboard.

        Warning

        This uses QClipboard and is known not to always work, depending on your window manager.

-q
    Do not quit when you accept an emoji.

    By default, when you accept an emoji (with the keyboard or with the mouse), jome:

        1. Prints the accept emoji or its codepoints to the standard output.

        2. Hides its window.

        3. Optional: Copies the accept emoji/codepoints to the clipboard (see the -b option).

        4. Optional: Executes a command (see the -c option) after 20 ms.

        5. If not running in server mode, quits (see the -s option).

    With the -q option, jome doesn’t hide its window and doesn’t quit when you accept an emoji so that you can make it print multiple emojis and/or execute a command multiple time with multiple emojis without restarting the application.

    You cannot specify the -q and -s options together.

-s NAME
    Start jome in server mode and set the server name to NAME.

    On Unix, this creates the socket file /tmp/NAME which must NOT exist before you start jome.

    You cannot specify the -s and -q options together.

  User interface

-d
    Use a dark background for emojis.

-C
    Hide the category list.

-L
    Hide the category labels in the emoji grid.

-R
    Hide the “Recent” category.

-r
    Include the recently accepted emojis in the results when finding emojis.

    In this case, jome shows the recently accepted emojis first within the result grid.

-k
    Hide the keyword list.

-w WIDTH
    Set the width of individual emojis to WIDTH pixels, amongst 16, 24, 32 (default), 40, or 48.

-P PERIOD
    Set the flashing period of the selection box to PERIOD ms (greater than or equal to 32).

    The selection box doesn’t flash by default.

-H COUNT
    Set the maximum number of recently accepted emojis to COUNT instead of 30.

FILES

~/.config/jome/emojis.json
    User-defined emoji keywords.

    See the “User-defined emoji keywords” section above.

EXIT STATUS

0 when you accept an emoji or 1 otherwise.

ABOUT

jome was originally written by and is maintained by, as of jome 1.3.0, Philippe Proulx (eepp).

GitHub project: ⟨https://github.com/eepp/jome⟩.

SEE ALSO

jome-ctl(1)