git.squeep.com Git - akkoma/blob - docs/docs/configuration/custom_emoji.md

   1 # Custom Emoji
   2
   3 Before you add your own custom emoji, check if they are available in an existing pack.
   4 See `Mix.Tasks.Pleroma.Emoji` for information about emoji packs.
   5
   6 To add custom emoji:
   7
   8 * Create the `STATIC-DIR/emoji/` directory if it doesn't exist
   9   (`STATIC-DIR` is configurable, `instance/static/` by default)
  10 * Create a directory with whatever name you want (custom is a good name to show the purpose of it).
  11   This will create a local emoji pack.
  12 * Put your `.png` emoji files in that directory. In case of conflicts, you can create an `emoji.txt`
  13   file in that directory and specify a custom shortcode using the following format:
  14   `shortcode, file-path, tag1, tag2, etc`. One emoji per line. Note that if you do so,
  15   you'll have to list all other emojis in the pack too.
  16 * Either restart Akkoma or connect to the iex session Akkoma's running and
  17   run `Pleroma.Emoji.reload/0` in it.
  18
  19 Example:
  20
  21 image files (in `instance/static/emoji/custom`): `happy.png` and `sad.png`
  22
  23 content of `emoji.txt`:
  24 ```
  25 happy, /emoji/custom/happy.png, Tag1,Tag2
  26 sad, /emoji/custom/sad.png, Tag1
  27 foo, /emoji/custom/foo.png
  28 ```
  29
  30 The files should be PNG (APNG is okay with `.png` for `image/png` Content-type) and under 50kb for compatibility with mastodon.
  31
  32 Default file extentions and locations for emojis are set in `config.exs`. To use different locations or file-extentions, add the `shortcode_globs` to your secrets file (`prod.secret.exs` or `dev.secret.exs`) and edit it. Note that not all fediverse-software will show emojis with other file extentions:
  33 ```elixir
  34 config :pleroma, :emoji, shortcode_globs: ["/emoji/custom/**/*.png", "/emoji/custom/**/*.gif"]
  35 ```
  36
  37 ## Emoji tags (groups)
  38
  39 Default tags are set in `config.exs`. To set your own tags, copy the structure to your secrets file (`prod.secret.exs` or `dev.secret.exs`) and edit it.
  40 ```elixir
  41 config :pleroma, :emoji,
  42   shortcode_globs: ["/emoji/custom/**/*.png"],
  43   groups: [
  44     Finmoji: "/finmoji/128px/*-128.png",
  45     Custom: ["/emoji/*.png", "/emoji/custom/*.png"]
  46   ]
  47 ```
  48
  49 Order of the `groups` matters, so to override default tags just put your group on top of the list. E.g:
  50 ```elixir
  51 config :pleroma, :emoji,
  52   shortcode_globs: ["/emoji/custom/**/*.png"],
  53   groups: [
  54     "Finmoji special": "/finmoji/128px/a_trusted_friend-128.png", # special file
  55     "Cirno": "/emoji/custom/cirno*.png", # png files in /emoji/custom/ which start with `cirno`
  56     "Special group": "/emoji/custom/special_folder/*.png", # png files in /emoji/custom/special_folder/
  57     "Another group": "/emoji/custom/special_folder/*/.png", # png files in /emoji/custom/special_folder/ subfolders
  58     Finmoji: "/finmoji/128px/*-128.png",
  59     Custom: ["/emoji/*.png", "/emoji/custom/*.png"]
  60   ]
  61 ```
  62
  63 Priority of tags assigns in emoji.txt and custom.txt:
  64
  65 `tag in file > special group setting in config.exs > default setting in config.exs`
  66
  67 Priority for globs:
  68
  69 `special group setting in config.exs > default setting in config.exs`
  70
  71 ## Stealing emoji
  72
  73 Managing your emoji can be hard work, and you just want to have the cool emoji your friends use? As usual, crime comes to the rescue!
  74
  75 You can use the `Pleroma.Web.ActivityPub.MRF.StealEmojiPolicy` [Message Rewrite Facility](../configuration/cheatsheet.md#mrf) to automatically add to your instance emoji that messages from specific servers contain. Note that this happens on message processing, so the emoji will be added only after your instance receives some interaction containing emoji _after_ configuring this.
  76
  77 To activate this you have to [configure](../configuration/cheatsheet.md#mrf_steal_emoji) it in your configuration file. For example if you wanted to steal any emoji that is not related to cinnamon and not larger than about 10K from `coolemoji.space` and `spiceenthusiasts.biz`, you would add the following:
  78 ```elixir
  79 config :pleroma, :mrf,
  80   policies: [
  81     Pleroma.Web.ActivityPub.MRF.StealEmojiPolicy
  82   ]
  83
  84 config :pleroma, :mrf_steal_emoji,
  85   hosts: [
  86     "coolemoji.space",
  87     "spiceenthusiasts.biz"
  88   ],
  89   rejected_shortcodes: [
  90     ".*cinnamon.*"
  91   ],
  92   size_limit: 10000
  93 ```
  94
  95 Note that this may not obey emoji licensing restrictions. It's extremely unlikely that anyone will care, but keep this in mind for when Nintendo starts their own instance.