Package: macmoji
MacMoji - Create custom emoji fonts for macOS.Desite Apple's tight control over iOS and macOS, there is a way to useanycustom emojis on Mac! :star_struck: Best part? Using a custom emoji font doesn't interfere with Apple's standard emoji font, so if you ever decide to go back to using the default emojis, you can do so with a single click.Table of contentsTable of contentsDemoInstallationDependenciesUser installationDeveloper installationUsageBasic usage1. Create assets2. Generate emoji font3. Install fontAssetsAdvanced namesHow it worksGenerating a custom fontFormatsTTX formatRecompilingLimitationsWorkaroundDemoComing soon:tm:InstallationDependenciesThis project has 3 main dependencies, allrequired for MacMoji to work:gear:cairolibffiAll can be installed viaHomebrew:brewinstallcairolibffigit-lfsUser installationOnce you have installed alldependencies, simply pip-install! :star_struck:pipinstallmacmojiYou should also verify the installation by runningmacmoji --versionand making sure a version number is printed. Check outUsagefor more info on how to actually use MacMoji!Developer installationIf you want to customize or contribute to MacMoji, here's the dev installation :technologist: Make sure you have the requireddependenciesinstalled before getting started!You will also need to have Poetry installed. Install instructionshere:pushpin:# git clone and cd into repogitclonecdmacmoji# Install dependenciespoetryinstall# Enter the poetry shellpoetryshellWhen running macmoji, usepython -m macmojiinstead of justmacmojiwith all commands, to ensure that Python uses the development version of MacMoji that you just set up!UsageBasic usageTo make your own first emoji font, you only need 3 commands!1. Create assetsThis creates all the required versions of the assets needed for generating the font. By default, MacMoji takes care of the outputs so you don't have to mind the output location. Read more about what assets should be in<assets_dir>here.macmojicreateassets<assets_dir>2. Generate emoji fontThis generates the emoji font that'll soon be used by your Mac. Unless you touched the output location when generating the assets, MacMoji will find your generated assets for you!macmojicreatefont3. Install fontMoves the generated emoji font file to the right location, which activates it right away! If you ever want to disable it, just runmacmoji uninstall.macmojiinstallThat's it! You've now created and activated your own custom emoji font on Mac :partying_face: :tada:AssetsFor every emoji you want to replace with your own version, you'll need either an.svgor high-res.pngfile. This should be named with the exact unicode value of the emoji. For most emojis, you can copy-paste the relevant codepoint from a website likeemojipedia.org. Here's an example of a valid assets folder:~/emoji-assets/
├── 1F528.svg        # Hammer
├── 1F600.svg        # Grinning face
├── 1F60D.png        # Heart-eyes
├── 1F636_1F32B.svg  # Face in clouds
└── 1F635_1F4AB.png  # Face with spiral eyesIn the example above, the final assets would ge generated by running:macmojicreateassets~/emoji-assetsAdvanced namesFor most emojis, the information above will be enough. However, some emojis have modifiers for gender, skin color, etc. These are named in a very specific way.The general format is:XXXXX.0-6.MWBGLR, with the following meanings:XXXXX: Unicode codepoint of the base emoji, ignoring leading zeroes. Codepoint don't need to include leading zeroes0-6: Skintone modifiers. Only 0-5 (going from lightest to darkest) are used in most emojis (see note about 6 below). Multiple can ve used at once in some emojisMWBG: Gender modifiers. M=Male, F=Female, B=Boy, G=Girl, L=Left, R=Right. Multiple can be used at once in some emojisExamples of valid file names (of course, either.svgor.pngare fine) and what emoji they represent:1F385.2.svg: Santa Claus, Medium-Light Skin Tone1F3C3.0.M.svg: Man Running Facing Right, No Skin Tone1F469_1F91D_1F468.55.svg: Woman and Man Holding Hands: Dark Skin ToneNote: foru1F9D1_u1F91D_u1F9D1.XX, X is 1-6 instead of 0-5, where the meaning of 6 is the same as 0 in the rest of the formats. From my observations, these are the only emojis with 6 modifiers.How it worksThe macOS font for emojis is calledApple Color Emoji.ttc. In order to change how emoji look, we need to create our own version of this font that takes priority over the default system font. Luckily for us, apps will prioritize user-installed fonts over system-wide ones, so there's a simple way to do this! :muscle:/System/Library/Fonts/Apple Color Emoji.ttc- system font~/Library/Fonts/Apple Color Emoji.ttc- our custom font :heart_eyes:Generating a custom fontIn broad terms, the custom emoji font file is generatad by taking Apple's base emojis, decompiling the font files, inserting your assets in the right sizes and formats, and recompiling. Here's a diagram to illustrate the process, before we dig deeper :nerd_face:FormatsThese are terms you might see a lot when using MacMoji. In essence, this is what the file types are for:TTC(TrueType Collection): a collection of multiple TTF files, combined into a single fileTTF(TrueType Font): all the data used for a single fontTTX: a decompiled version of a TTF fileSo far so easy, but we now enter the world offont filesand theTrueTypespecification :face_with_spiral_eyes: Apple uses a special table in the TrueType files calledSBIXfor storing the actual image data for the emoji fonts. This table contains a bunch ofstrikes, each of which containing all the assets for an emoji at that exact size.During the decompilation stage, MacMoji splits the TTC file into the TTF files that it contains, in this case the two following files:AppleColorEmoji.ttf.AppleColorEmojiUI.ttfThe TTF files are very, very similar, so for this project they'll basically be treated as the same. The TTF files are then decompiled into TTX files with the same names (except extension, of course).TTX formatThe TTX file is where MacMoji does most of the actual emoji replacement. In the code snippet below, you can see an example of how aSBIXtable might look in a TTX file. The relevant portion for this project is the<strike>tag, which contains all the assets (and data) needed for displaying all emojis at a given size. In the snippet,<ppem value="20" />tells us that the size of the emojis at that strike is20px.The data for every individual emoji is under a<glyph>tag per emoji. Thenameattribute signals what emoji is being referred to, while the<hexdata>tag inside is filled with the hexadecimal representation of the data from a PNG file at the given size, for that emoji. MacMoji automatically inserts the new emoji assets at all the relevant places in the TTX files.<sbix><versionvalue="1"/><flagsvalue="00000000 00000001"/><strike><ppemvalue="20"/><resolutionvalue="72"/><glyphname=".notdef"/>...<glyphgraphicType="png "name="u0023_u20E3"originOffsetX="0"originOffsetY="0"><hexdata>...</hexdata></glyph>...</strike>...</sbix>RecompilingRecompiling the modified TTX files into TTF and then a single TTC file is basically the same process as splitting them up, but in reverse :exploding_head:LimitationsIf you use the default way of installing your custom font (macmoji install), the emojis will update basically everywhere. However, a few notable exceptions are:WebKit: affects Safari (but not other browsers like Chrome and Firefix, since they're using a different rendering engine than WebKit)Some Adobe apps: affects Illustrator, Photoshop and (while selecting text) XD. Other adobe apps have not been testedWorkaroundBy default, MacMoji installs the custom emoji font to~/Library/Fonts/Apple Color Emoji.ttc, which only affects the user's emoji configuration (see#how-it-works). However, from reading WebKit's source code I'm under the impression that WebKit links directly to Apple's source emoji font file at/System/Library/Fonts/Apple Color Emoji.ttc, and it's possible that Adobe is doing something similar in the older apps.Byreplacingthe system emoji font, you should be able to get WebKit to use the correct emoji font. However, this requires somechanges to the system filesthat you shouldnotattempt if you don't know what you're doing. I have not yet tested this, and can't confirm that it works, but if some brave soul wants to help out, I'd love to hear how it goes!