{"id":14982564,"url":"https://github.com/quotient-im/quaternion","last_synced_at":"2025-05-15T04:00:15.409Z","repository":{"id":37334538,"uuid":"50142756","full_name":"quotient-im/Quaternion","owner":"quotient-im","description":"A Qt-based IM client for Matrix","archived":false,"fork":false,"pushed_at":"2025-03-25T10:40:01.000Z","size":8412,"stargazers_count":663,"open_issues_count":141,"forks_count":108,"subscribers_count":30,"default_branch":"dev","last_synced_at":"2025-04-14T01:59:05.210Z","etag":null,"topics":["c-plus-plus","chat","chat-application","client","hacktoberfest","matrix","qt","qt5"],"latest_commit_sha":null,"homepage":"https://matrix.org/ecosystem/clients/quaternion/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/quotient-im.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-01-21T23:03:04.000Z","updated_at":"2025-04-05T21:40:03.000Z","dependencies_parsed_at":"2024-02-27T10:25:37.791Z","dependency_job_id":"fdf8c017-8162-4bfb-9244-cd6e0c51b3c9","html_url":"https://github.com/quotient-im/Quaternion","commit_stats":{"total_commits":2139,"total_committers":44,"mean_commits":48.61363636363637,"dds":"0.23562412342215988","last_synced_commit":"54958f32ce37ffd9428b1bc7203dfa39b75b8170"},"previous_names":["qmatrixclient/quaternion"],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quotient-im%2FQuaternion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quotient-im%2FQuaternion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quotient-im%2FQuaternion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quotient-im%2FQuaternion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quotient-im","download_url":"https://codeload.github.com/quotient-im/Quaternion/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254270640,"owners_count":22042858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c-plus-plus","chat","chat-application","client","hacktoberfest","matrix","qt","qt5"],"created_at":"2024-09-24T14:05:39.608Z","updated_at":"2025-05-15T04:00:15.198Z","avatar_url":"https://github.com/quotient-im.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Quaternion\n\n![status](https://img.shields.io/badge/status-beta-yellow.svg)\n[![release](https://img.shields.io/github/release/quotient-im/quaternion/all.svg)](https://github.com/quotient-im/Quaternion/releases/latest)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/1663/badge)](https://www.bestpractices.dev/projects/1663)\n[![](https://img.shields.io/matrix/quotient:matrix.org.svg)](https://matrix.to/#/#quotient:matrix.org)\n[![CI builds hosted by: Cloudsmith](https://img.shields.io/badge/OSS%20hosting%20by-cloudsmith-blue?logo=cloudsmith\u0026style=flat-square)](https://cloudsmith.com)\n\nQuaternion is a cross-platform desktop IM client for the\n[Matrix](https://matrix.org) protocol. You can find general information about\napplication usage and settings here. See [BUILDING.md](./BUILDING.md) for\nbuilding instructions.\n\n## Contacts\nMost of talking around Quaternion happens in the room of its parent project,\nQuotient: [#quotient:matrix.org](https://matrix.to/#/#quotient:matrix.org).\nYou can file issues at\n[the project's issue tracker](https://github.com/quotient-im/Quaternion/issues).\nIf you find what looks like a security issue, please follow\n[special instructions](./SECURITY.md).\n\n\n## Downloading and installing\n\nThe recommended way to install Quaternion is as follows (make sure to read\nthe notes below depending to your environment):\n\n- on GNU/Linux - using your distribution's package manager;\n- on macOS - from Homebrew;\n- on Windows - from an archive at the project's\n  [GitHub Releases page](https://github.com/quotient-im/Quaternion/releases).\n\nThe source code is [hosted at GitHub](https://github.com/quotient-im/Quaternion).\n\n### Requirements\n\nQuaternion 0.0.97.1 needs Qt version 6.4 or higher.\n\n### Linux\nQuaternion is packaged for many distributions, including various versions of\nDebian, Ubuntu and OpenSUSE, as well as Arch Linux, NixOS and FreeBSD.\nA pretty comprehensive up-to-date list can be found at\n[Repology](https://repology.org/project/quaternion/versions). Popular\ndistributions satisfying the mentioned Qt requirement are Debian 12 (Bookworm),\nUbuntu 24.04 (noble), Fedora 39, OpenSUSE Leap 15.6; anything newer than that\nshould be fine, too.\n\nOn top of the Quaternion package, you should not normally need to install anything in addition;\nif something is not working due to a missing dependency, it's a bug in the package - please\nreport it to your distribution's Quaternion packager, _not_ to this repository.\n\nThere are also flatpaks for Quaternion available from Flathub. To install, use:\n\n```\nflatpak install https://flathub.org/repo/appstream/io.github.quotient_im.Quaternion.flatpakref\n```\n\nThese packages are built with a suitable KDE runtime. You can install them on\nany distribution that has Flatpak - even if it's older than mentioned above.\nPlease file issues at https://github.com/flathub/io.github.quotient_im.Quaternion\nif you believe there's a problem specific to the Flatpak package of Quaternion.\n\n### Windows\nSince there's no established package management on Windows to resolve\ndependencies, all needed libraries and a C++ runtime are packaged/installed\ntogether with Quaternion - except OpenSSL. Unless you already have OpenSSL\naround (e.g., it is a part of any Qt development installation), you should\ninstall it yourself.\n[OpenSSL's Wiki](https://wiki.openssl.org/index.php/Binaries) lists a few links\nto OpenSSL installers. They come in different build configurations; current\nQuaternion builds distributed from GitHub Releases need OpenSSL 3.x made\nwith/for Visual Studio (not MinGW).\n\n### macOS\nIf you use Homebrew (you should!), `brew install quaternion` installs Quaternion\nalong with its dependencies. Otherwise, packages published at\n[GitHub Releases](https://github.com/quotient-im/Quaternion/releases/latest)\ncome with everything necessary already bundled.\n\n### Development builds\n\nThanks to generous and supportive folks at [Cloudsmith](https://cloudsmith.io)\nwho provide free hosting to OSS projects, those who want to check out the latest\n(not necessarily the greatest, see below) code can find packages produced by\ncontinuous integration (CI) in the\n[Quaternion repo there](https://cloudsmith.io/~quotient/repos/quaternion/groups/).\n\nA few important notes on these packages in case you're new to them:\n- All of them come bundled with fairly recent (not necessarily latest) Qt 6.\n- They are only provided for testing; feedback on _any_ release is welcome\n  as long as you know which build you run, but do not expect the developers\n  to address issues in older snapshots.\n- In case it's still unclear: these builds are UNSTABLE by default; some may\n  not run at all, and if they do, they may ~~tell you obscenities in your\n  local language, steal your smartphone, and share your private photos~~\n  scramble the messages you send, interfere with or even break other clients\n  including Element ones, and generally corrupt your account in ways unexpected\n  and hard to fix (all of that actually happened in the past). Do NOT run these\n  builds if you're not prepared to deal with the problems.\n- If you understand the above, have your backups in order and are still willing to try things out\n  or just generally help with the project - make sure to `/join #quotient:matrix.org` and have\n  the URL you downloaded Quaternion from. In case of trouble, ~~show this label to your doctor~~\n  send the URL to the binary you used in the chat room (you may have to use another client or\n  Quaternion version for that), describe what happened and we'll try to pull you out of it.\n\nIf you want to build Quaternion from sources, see [BUILDING.md](./BUILDING.md).\n\n\n## Running\nJust start the executable in your most preferred way - either from the build\ndirectory or from the installed location. If you're interested in tweaking\nconfiguration beyond what's available in the UI, read the \"Configuration\"\nsection further below.\n\n\n## Translation\nQuaternion uses [Lokalise.co](https://lokalise.co) for the translation effort.\nIt's easy to participate:\n[join the project at Lokalise.co](https://lokalise.co/public/730769035bbc328c31e863.62506391/);\nif your language is not there, ask to add it (either in\n[#quotient:matrix.org](https://matrix.to/#/#quotient:matrix.org) or in\nthe Lokalise project chat); and start translating! Many languages are still\nlonging for contributors.\n\n\n## Configuration\nThe only non-trivial command-line option available so far is `--locale` - it\nallows you to override the locale Quaternion uses (an equivalent of setting\n`LC_ALL` variable on UNIX-based systems). German, Russian, Polish, and Spanish translations are\neither complete or mostly complete, as of this writing.\n\nQuaternion stores its configuration in a way standard for Qt applications, as\ndescribed below. It will read and write the configuration in the user-specific\nlocation (creating it if non-existent) and will only read the system-wide\nlocation with reasonable defaults if the configuration is not found at\nthe user-specific one.\n\n- Linux:\n  - user-specific: `$HOME/.config/Quotient/quaternion.conf`\n  - system-wide: `$XDG_CONFIG_DIR/Quotient/quaternion` or\n    `/etc/xdg/Quotient/quaternion`\n- macOS:\n  - user-specific: `$HOME/Library/Preferences/im.quotient.quaternion.plist`\n  - system-wide: `/Library/Preferences/im.quotient.quaternion.plist`\n- Windows: registry keys under\n  - user-specific: `HKEY_CURRENT_USER\\Software\\Quotient\\quaternion`\n  - system-wide: `HKEY_LOCAL_MACHINE\\Software\\Quotient\\quaternion`\n\nALL settings listed below reside in `UI` section of the configuration file\nor (for Windows) registry.\n\nSome settings exposed in the user interface (Settings and View menus) are:\n\n- `notifications` - a general setting whether Quaternion should distract\n  the user with notifications and how.\n  - `none` suppresses notifications entirely (rooms and messages are still\n    hightlighted but the tray icon is muted);\n  - `non-intrusive` allows the tray icon show notification popups;\n  - `intrusive` (default) adds to that activation of Quaternion window\n    (i.e. the application blinking in the task bar, or getting raised,\n    or otherwise demands attention in an environment-specific way).\n- `timeline_layout` - this allows to choose the timeline layout. If this is\n  set to \"xchat\", Quaternion will show the author to the left of each message,\n  in an xchat/hexchat style. Any other value will select the \"default\" layout,\n  with author labels above blocks of messages.\n- `use_shuttle_dial` - Quaternion will use a shuttle dial instead of a classic scrollbar for\n  the timeline's vertical scrolling control. To start scrolling move the shuttle dial away from its\n  neutral position in the middle; the further away you move it, the faster you scroll in that\n  direction. Releasing the dial resets it back to the neutral position and stops scrolling.\n  This is more convenient than the classic scrollbar when you need to move around with bounds of\n  the timeline constantly changing, as is the case of a Matrix timeline (older messages get loaded\n  as you scroll back, and new messages can come from sync too, making the classic scrollbar jump\n  around); with that said, the control is somewhat unconventional and not all people like it.\n  The shuttle dial is enabled by default; set this to false (or 0) to use the classic scrollbar.\n- `autoload_images` - whether full-size images should be loaded immediately once the message is\n  shown on the screen. The default is to automatically load full-size images; set this to false\n  (or 0) to disable that and only load a thumbnail in the timeline (with the full image downloaded\n  after you click \"Save as\" or \"Open\" in the context menu) but be aware that if a message doesn't\n  have a thumbnail at all you won't see anything (see also\n  https://github.com/quotient-im/Quaternion/issues/601).\n- `show_spammy` (\"Show no-effect activity\" in the menu) - when set to `false`, this setting tries\n  to clean up the timeline from events that don't contribute to conversation in any reasonable way,\n  such as messages from a recently joined user that are all redacted - a typical case of moderation\n  applied to spam.\n- `RoomsDock/tags_order` - allows to alter the order of tags in the room\n  list. This is a comma-separated list of tags/namespaces;\n  a few characters have special meaning as described below. If a tag is\n  not mentioned and does not fit any namespace, it will be put at the end of\n  the room list in lexicographic order. Tags within the same namespace are\n  also ordered lexicographically.\n  \n  `.*` (only recognised at the end of the string) means the whole namespace;\n  strings that don't end with this are treated as fully specified tags.\n  \n  `-` in front of the tag/namespace means it should not be used for grouping;\n  e.g., if you don't want People group you can add `-im.quotient.direct`\n  anywhere in the list. `im.quotient.none` (\"Rooms\") always exists and\n  cannot be disabled, only its position in the list is taken into account.\n  \n  The default tags order is as follows:\n  `m.favourite,u.*,im.quotient.direct,im.quotient.none,m.lowpriority`,\n  meaning: Favourites, followed by all user custom tags, then People,\n  rooms with no enabled tags (the \"Rooms\" group) and finally Low priority\n  rooms. If Quaternion doesn't find the setting in the configuration it\n  will write down this line to the configuration so that you don't need\n  to enter it from scratch.\n\nSettings not exposed in UI:\n\n- `show_author_avatars` - set this to 1 (or true) to show author avatars in\n  the timeline (default if the timeline layout is set to default); setting this\n  to 0 (or false) will suppress avatars (default for the XChat timeline layout).\n- `suppress_local_echo` - set this to 1 (or true) to suppress showing local\n  echo (events sent from the current application but not yet confirmed by\n  the server). By default local echo is shown.\n- `animations_duration_ms` - defines the base duration (in milliseconds) of\n  animation effects in the timline. The default is 400; set it to 0 to disable\n  animation.\n- `outgoing_color` - set this to the name or hex code (3- or 6-digit) of the colour you prefer\n  for text you sent; by default it's `#4A8780` (a brownish tint of teal - no science behind that,\n  just an arbitrary shot in a color picker).\n- `highlight_color` - set this to the name or hex code (3- or 6-digit) of the colour you prefer\n  for highlighted rooms/messages; by default it's `orange`.\n- `highlight_mode` - set this to `text` if you prefer to use the text color\n  for highlighting; the default is to use the background for highlighting.\n- `use_human_friendly_dates` - set this to false (or 0) if you do NOT want\n  usage of human-friendly dates (\"Today\", \"Monday\" instead of the standard\n  day-month-year triad) in the UI; the default is true.\n- `show_noop_events` - set this to 1 to show state events that do not alter\n  the state (you'll see \"(repeated)\" next to most of those).\n- `quote_style` - the quote template. `\\\\1` means the quoted string; by default it's `\u003e \\\\1\\n`\n  (i.e., `\u003e ` prepended before each line of the quoted string).\n- `quote_regex` - set to `^([\\\\s\\\\S]*)` to add `UI/quote_style` only at the beginning and the end\n  of the quote; by default it's `(.+)(?:\\n|$)`, meaning that each line is quoted with `quote_style`\n  separately.\n- `Fonts/render_type` - select how to render fonts in Quaternion timeline;\n  possible values are \"NativeRendering\" (default) and \"QtRendering\".\n- `Fonts/family` - override the font family for the whole application.\n  If not specified, the default font for your environment is used.\n- `Fonts/pointSize` - override the font size (in points) for the whole\n  application. If not specified, the default size for your environment is used.\n- `Fonts/timeline_family` - font family (for example `Monospace`) to\n  display messages in the timeline. If not specified, the application-wide font\n  family is used.\n- `Fonts/timeline_pointSize` - font size (in points) to display messages\n  in the timeline. If not specified, the application-wide point size is used.\n- `maybe_read_timer` - threshold time interval in milliseconds for a displayed\n  message to be considered as read if it's still displayed after that interval.\n- `hyperlink_users` - set this to false (or 0) if you do NOT want to hyperlink matrix user IDs\n  in messages; by default it's true, meaning that user IDs will be turned to hyperlinks\n- `auto_markdown` (EXPERIMENTAL) - since version 0.0.95 Quaternion has experimental support for\n  Markdown when entering messages. Normally, Quaternion only treats the message as Markdown if\n  it is prepended by `/md` command (the command itself is removed from the message before sending).\n  Setting `auto_markdown` to `true` enables Markdown parsing in all messages unless you prepend\n  `/plain`. By default, this setting is `false` since the current support of Markdown by Qt is\n  buggy, and the implementation in Quaternion has its own quirks on top of that. If you have it\n  enabled (or use `/md` command) feel free to report any bugs with it at the usual place.\n- `paste_plaintext_by_default` - set this to false (or 0) if you want to paste\n  formatted text by default.\n\nQuaternion uses Qt Keychain to store access tokens and database pickles. If\nthe secure storage supported by Qt Keychain is not available, Quaternion\nwill not be able to store your access token(s) and pickles and will\nautomatically disable E2EE to avoid unrecoverable encrypted messages.\nThe fallback file used by Quaternion pre-0.0.96 is no more used.\n\nQuaternion caches the rooms state and user/room avatars on the file system\nin a conventional location for your platform, as follows:\n\n- Linux: `$HOME/.cache/Quotient/quaternion`\n- macOS: `$HOME/Library/Cache/Quotient/quaternion`\n- Windows: `%LOCALAPPDATA%/Quotient/quaternion/cache`\n\nCache files are safe to delete at any time but Quaternion only looks for them\nwhen starting up and overwrites them regularly while running; so it only\nmakes sense to delete cache files when Quaternion is not running. If Quaternion\ndoesn't find or cannot fully load cache files at startup it downloads\nthe whole state from Matrix servers. It tries to optimise this process by\nlazy-loading room members if the server supports that; in an unlucky case when\nthe server cannot do lazy-loading, initial sync can take much time (up to\na minute and even more, depending on the number of rooms and the number of users\nin them).\n\nDeleting cache files may help with problems such as missing avatars,\nrooms stuck in a wrong state etc.\n\n\n## Troubleshooting\n\nQuaternion uses libQuotient under the hood; some Quaternion problems are\nactually problems of libQuotient. If you haven't found your case below, check\nalso the troubleshooting section in libQuotient README.md.\n\n#### Failure to start on Windows\nIf you try to start Quaternion from a path that is in your `%PATH%` variable it's very likely to\nmiss all the libraries that reside in subdirectories of the package. Make sure that you start\nQuaternion (either from the command line or Explorer) with the current directory being that of\n`quaternion.exe` binary.\n\n#### Some older messages don't get decrypted in E2EE rooms\nUnfortunately, this is a limitation in the libQuotient code. The E2EE backend of libQuotient is\ncurrently being ported from Olm to matrix-rust-sdk - aside from being maintained, unlike Olm,\nmatrix-rust-sdk provides higher-level API withh all necessary bits and pieces to decrypt messages,\nso libQuotient won't have to reimplement it. Subscribe to\n[the respective pull request](https://github.com/quotient-im/libQuotient/pull/820)\nif you want to be updated on the progress of this work.\n\n#### No messages in the timeline\nIf Quaternion runs but you can't see any messages in the chat (though you can\ntype them in) - you might not have Qt Quick libraries and/or plugins installed.\nOn Linux, this may be a case when you are not using the official packages for\nyour distro. Check the stdout/stderr logs, they are quite clear in such cases.\nOn Windows, Mac, and when using Flatpak, just open an issue (see \"Contacts\"\nin the beginning of this file) because most likely not all necessary Qt parts\nwere packaged along with Quaternion.\n\n#### SSL problems\nEspecially on Windows, if Quaternion starts up but upon an attempt to connect\nreturns a message like \"Failed to make SSL context\" - correct SSL libraries\nare not reachable by the Quaternion binary. Re-read the chapter \"Requirements\",\nsection \"Windows\" in the beginning of this file and do as it advises (make sure\nin particular that you use the correct version of OpenSSL - it should be 3.x,\nnot 1.x).\n\n#### Logging\nIf you want to see log messages in the command-line console (by default,\nthey are sent to system log on Windows and some but not all Linux systems with\njournald), set `QT_ASSUME_STDERR_HAS_CONSOLE=1` to force the output to be\nredirected to the console.\n\nWhen chasing bugs and investigating crashes, it helps to run Quaternion from\nthe command line with increased logging level. Both libQuotient and (since\n0.0.96 beta 4) Quaternion use\n[logging categories](https://doc.qt.io/qt-6/qloggingcategory.html#configuring-categories)\nto allow fine-grained switching of logs for a given part of the code. Quaternion\nand libQuotient use different categories; this text only describes those for\nQuaternion, make sure to also check [lib/README.md](lib/README.md) for\nlibQuotient logging categories. The most practical way to configure logging in\norder to debug a problem is via the `QT_LOGGING_RULES` environment variable;\nthe Qt documentation (see the link above) lists a few other methods. In all\ncases, you need to provide one or several clauses that look as follows:\n```\nquaternion.\u003ccategory\u003e.\u003clevel\u003e=\u003cflag\u003e\n```\nwhere\n- `\u003ccategory\u003e` is one of (see also `client/logging_categories.h`):\n  - `main`\n  - `accountselector`\n  - `models` (Quaternion backend for user and room lists)\n  - `models.events` (same for events)\n  - `timeline` (C++ code for timeline visuals - very few log lines and not very\n    informative unless you know what to look for)\n  - `timeline.qml` (QML code for timeline visuals - this is what you likely\n    need to figure out why the timeline looks wrong)\n  - `htmlfilter` (conversions between Qt and Matrix subsets of HTML as well\n    as HTML import from other applications)\n  - `messageinput` (message entry box)\n  - `thumbnails` (the code to supply images for the timeline)\n- `\u003clevel\u003e` is one of `debug`, `info`, and `warning`;\n- `\u003cflag\u003e` is either `true` or `false`.\n\nBear in mind that all logging categories for Quaternion start with `quaternion`\nwhile logging categories for libQuotient always start with `quotient`.\n\nYou can use `*` (asterisk) as a wildcard for any part between two dots, and\na semicolon is used for a separator. Latter statements override former ones, so\nif you want Quaternion to log at debug level except, e.g., `timeline.qml`, set\n```shell script\nQT_LOGGING_RULES=\"quaternion.*.debug=true;quaternion.timeline.qml.debug=false\"\n```\n\nYou may also want to set `QT_MESSAGE_PATTERN` to make logs slightly more\ninformative (see https://doc.qt.io/qt-6/qtlogging.html#qSetMessagePattern\nfor the format description). My (@kitsune's) `QT_MESSAGE_PATTERN` looks as\nfollows:\n```\n`%{time h:mm:ss.zzz}|%{category}|%{if-debug}D%{endif}%{if-info}I%{endif}%{if-warning}W%{endif}%{if-critical}C%{endif}%{if-fatal}F%{endif}|%{message}`\n```\n(the scary `%{if}`s are just encoding the logging level into its initial letter).\n\n## Screenshot\n![Screenshot](Screenshot.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquotient-im%2Fquaternion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquotient-im%2Fquaternion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquotient-im%2Fquaternion/lists"}