We use the Matrix instant messaging system at Edgeryders for collaborating among our teams on projects. This wiki documents how to use your Matrix ID for communication with the most common Matrix client software âElementâ (formerly called âRiotâ).
Content
3. First steps with your Matrix account
- 4.1. Formatting your content
- 4.2. Posting pictures and files
- 4.3. Getting peopleâs attention
- 4.4. Creating and managing rooms and chats
- 4.5. Voice calls, video calls, screensharing
- 4.6. Voice messaging
- 4.7. Sharing login credentials and other secrets
- 4.8. Resetting your password
- 4.9. Other tips and tricks
5. Edgerydersâ Matrix addressbook
1. Getting a Matrix account
As a collaborator on an Edgeryders project, youâll need a Matrix account (or more formally, a âMatrix IDâ). Itâs simple:
-
Create an edgeryders.eu account. Because your Matrix account username will be the same as your edgeryders.eu username.
-
Ask @matthias to create an
@username:edgeryders.eu
Matrix account for you. Ask by direct message here on the edgeryders.eu platform, or by e-mail to matthias@edgeryders.eu. You will receive your password to your e-mail address.
How Matrix IDs look. Matrix IDs have the form @localpart:domainpart.tld
. Similar to e-mail addresses, they have a âlocalpartâ and a âdomain partâ. The punctuation is a bit different than in e-mail addresses to avoid confusing them. For Edgeryders, we are running our own Matrix software on our own server, so the âdomain partâ is always edgeryders.eu
. The âlocalpartâ is always the same as your edgeryders.eu username (in all-lowercase).
Do not use a federated Matrix account. To collaborate on Edgeryders projects, please get a @username:edgeryders.eu
account as instructed above. Because we disabled federation, it is not possible to get an account at a different Matrix homeserver (such as :matrix.org
, available for free) and to use that to participate in Edgerydersâ Matrix chats. The reasons for us disabling the federation features are:
-
There are still some bugs in Matrix for presence notifications across federated servers, which means users with an
:edgeryders.eu
account may not see people with:matrix.org
accounts as online, and vice versa. -
Chat messages in rooms with users from different Matrix homeservers are permanently stored on these multiple homeservers, not just on our own. This is a privacy / confidentiality issue (possibly even clashing with the GDPR), except if we would consistently use end-to-end encryption to enforce that these messages are stored in an encrypted manner. However, there are still some software issues with end-to-end encryption in Matrix and it is generally annoying to use, so itâs not advisable to do this for cases like this where we have the alternative to keep all messages confined to our server.
2. Logging in to Element
In the browser. We have an own Matrix server running and disabled federation with other Matrix servers, so all your messages are saved only on our own server. However, we do not have our own application installed to actually use Matrix. Instead, you can use the free and open source software âElementâ to communicate over Matrix.
You can log in as follows (normally you never log out, so this is a one-time thing per browser):
-
Open this link in a new tab: Element
-
Choose: âSign in with: Usernameâ.
-
Enter your username in the form
@username:edgeryders.eu
, as found in the e-mail you received or in our âMatrix addressbookâ below. You can not use your e-mail address for login because of the way we have set up our Matrix server. -
Press Tab or click into the password field. The software will now automatically change and fill some fields, so that you should see a message âSign in to your Matrix account on edgeryders.euâ. See under âlogin issuesâ below if you donât have that message.
-
Enter your password (as received in the e-mail from @matthias).
-
Click on Sign in.
Login issues in the browser.
-
âInvalid homeserver discovery response.â If you see that error message, and the login screen still shows âSign in to your Matrix account on matrix.orgâ instead of âSign in to your Matrix account on edgeryders.euâ, then your browser cannot figure out on which server your account has been registered. Try the following steps to fix this:
-
Disable Privacy Badger. Privacy Badger can prevent you from logging into the Matrix server. This issue was reported with Firefox Quantum 69.0 (64-bit) for Mac and Privacy Badger 2019.7.1.1. The problem went away after disabling Privacy Badger for the element.io website.
-
Disable other privacy enhancing extensions. It is possible that adblockers or privacy extensions like Ghostery block the requests to edgeryders.eu and matrix.edgeryders.eu for login. Try disabling these extensions on element.io, or first try if login works in a private window / incognito mode (where extensions are typically disabled already).
-
Enter the homeserver manually. This should always work, but is another manual step during login. After the message âSign in to your Matrix account on matrix.orgâ click the link âChangeâ an in the field âHomeserver URLâ enter
https://matrix.edgeryders.eu:8448
. Enter the URL exactly as given above. Even a small deviation like a trailing slash will make this fail, which is an issue we have reported.
-
-
Firefox login issues. Generally, Element works in a recent Firefox browser. However, if login does not work in Firefox using the normal procedure above, try it in a Firefox Private Window instead (see issue #11844).
On a smartphone. To be available on the go, you probably want to install a Matrix client software on your smartphone as well. For that, the Riot.im software is also available as mobile apps for Android and for iOS.
Here is the login procedure for the Android app:
-
Open the installed app, called âElement (Riot.im)â on the app icon.
-
Click âGet Startedâ, then click âLog in with Matrix IDâ.
-
Enter your username in the form
@username:edgeryders.eu
, as found in the e-mail you received or in our âMatrix addressbookâ below. You can not use your e-mail address for login because of the way we have set up our Matrix server. -
Enter your password (as received in the e-mail you received from @matthias).
-
Click âSign inâ.
3. First steps with your Matrix account
After log in, here are some first steps to do in the Matrix software:
-
Accept the invitations. Your Matrix account has already been invited to one or several rooms by the admin who created your account. So, please accept the invitation on the left side of the screen (when using Matrix in your browser). Attention: The âCampfireâ is a public socializing corner where we invite everyone from Edgeryders and our networks with a Matrix account. So please donât put anything even remotely confidential there
-
Adapt your account settings. Click the gear icon in the left bottom part to go to your account settings. There:
-
Connect an e-mail address. (Note: For now, it will be possible to find your Matrix account under this e-mail address on the vector.im identity server, so use one that you are ok with for this purpose.)
-
Change your password â this is important, because the one above was not safely transmitted via e-mail. Instructions: (1) first connect an e-mail address, as mentioned above, (2) change the password in the account settings, (3) click the confirmation link in the e-mail sent to your e-mail address, (4) after the confirmation âpassword successfully changedâ, ignore the warning about exporting and reimporting keys since you have not sent or read any encrypted messages by now.
-
Change your display name â also important, because important functionalities like mentions and invitations do not work as well if you do not do this. By default, you will appear as â@username:edgeryders.euâ in chat logs and as room name of your direct chats, which is ugly. We propose to set the display name to your localpart, so just âusernameâ in this case, to keep things simple. Due to a software bug, you canât do this in one step yet. So change the display name to something else first, close the settings, then reopen it again and change it to the localpart of your Matrix ID (with lowercase first letter, please!).
-
Add a profile picture.
-
Enable e-mail notifications. There is an option in the account settings to do this for the e-mail address you just connected to your account. You will then get e-mails about messages received while you were offline / unresponsive.
-
Enable @all notifications. To get everyoneâs attention in a long-running team chat where most people have set the notification level to âMentions onlyâ, this is a nice trick. In line âNotifications â Messages containing keywordsâ, click on âkeywordsâ and enter â@allâ (without the ââ). Confirm, then set âMessages containing keywordsâ to âNoisyâ. Youâll see a red message and get @mention equivalent notifications when somebody types @all.
-
Enable âNew Composer & Autocompleteâ. (Optional.) To get nice but âexperimentalâ buttons for adding simple formatting to your messages, and for adding emojis with autocomplete after typing a colon â:â and a keyword.
-
Reduce the default notification level to âMentions onlyâ. This is ok for a team chat if you want to reduce notification frequency. Youâll still see red bubbles with ânew messagesâ counters in chats so you can catch up, but you will only get notifications (little desktop overlay window, sounds, e-mail message) for your @username mentions and for @all. To set this up, mouse over the âOpen Village MENA: Teamâ room in the room list, click the ââŚâ on-hover button and choose âMentions onlyâ.
-
Mobile app: Shorten the âsync request delayâ time. In the Android mobile app, this is done under ââ° â Settings â Delay between two sync requestsâ. The default value is 600 s. Set it to around 60 s instead. Otherwise, you would get all messages 10 minutes (!) after they are sent in cases when Matrix is not the Android foreground app. And that probably includes âwhen the screen is locked or offâ.
-
4. Advanced topics
4.1. Formatting your content
Formatting messages. Matrix messages support basic Markdown syntax for formatting â see the complete syntax reference. Some is also available from buttons after enabling the âNew Composer & Autocompleteâ option in your account settings. Some is not, for example the code for proper hyperlinks: to create a link like this, you would write this text into your message: [like this](http://example.com/)
.
Emojis. With the âNew Composer & Autocompleteâ option enabled in your account settings, you get emoji auto-complete after typing a colon â:â and the start of an emojiâs name. The complete list of named emojis is available in an emoji cheat sheet and the emoji codes reference. (Images may look slightly different though, as Riot uses an EmojiOne emoji font in a different version, probably the last fully open source version EmojiOne v2, here on Github.)
It is even possible to include emojis into your display name â they will show up as little colorful images whenever your username is displayed. You configure this either by putting the equivalent Unicode character (like the one for âghostâ) into the âSettings â Display nameâ field. Or by doing the same with a slash command and the emoji code in a message: /nick someword :ghost:
. This also means that when mentioning your display name, the emoji has to be included for a mention notification to work! Not a problem when only appending the emoji to a normal text username, as people can use autocomplete for mentioning. And esp. not a problem when keeping the textual part of such a username the same as the localpart in @localpart:edgeryders.eu, as then the mention will also work when somebody omits the emoji, as itâs still a valid Matrix ID, and mentions also work for these.
4.2. Posting pictures and files
Sharing images and other files. It is possible to share any files to a chat room, using the âUpload Fileâ button in the message editor. Uploaded images will be displayed inside the chat, other uploaded files will be offered for download. When the chat is end-to-end encrypted, the files will also be saved encrypted on our server, in which case nobody outside of the chatroom (not even the server admin) can access their content. Please delete the messages with large files (>1 MiB) after the other people in the chat downloaded them. It will help us keep the backup sizes small. Even better is to upload the files to a shared folder (like, Google Drive) and to only post the link to them in the chatroom.
Posting images from the clipboard. It is possible to post images to a chatroom from the clipboard, which is faster for sharing images than to save an image from the browser to a file first. Tested with Chrome / Chromium 60. Instructions:
- In your browser, right-click on the image you want to share in the chatroom.
- Click âCopy imageâ.
- Right-click in the Matrix chat message editor and select âPasteâ (or just press Ctrl+V while the keyboard focus is on the chat message editor).
- A popup window will appear asking if you want to upload the image from your clipboard to share i in the chatroom. Confirm that.
4.3. Getting peopleâs attention
Getting peopleâs attention. Weâll have to experiment to find best practices for a long-running team chat without constant notification spam. The current proposal is this one though: Assume everyone in the project team chat has notifications set to âMentions onlyâ for this room. They will probably catch up with all messages at some time, but you canât rely on that. So use mentions to get their attention â username
, Username
, @username
and @username:edgeryders.eu
all work and produce a red message on the receiverâs side, and a notification (desktop notification, sound, e-mail after 10 minutes). Please note: when you try to mention someone who has not changed their default display name, autocomplete will not work, and you will have to type the whole @username:edgeryders.eu
.
When you really need the attention of everyone in the chat, in theory you can use @all
to the same effect. This assumes everyone made the required keyword notifications setup as described above, which in practice will be a completely wrong assumption.
How e-mail notifications work. After setting up your Matrix account as instructed above by connecting your e-mail address and enabling it as a notification target, you will receive e-mail notifications about Matrix messages you received while offline, or that you rceived but did not yet read in your browser / mobile app. Quite similar to how it works with Facebook messages. In more detail, the timers work like this for each Matrix âroomâ individually (however if any e-mail is sent, it will include all accumulated e-mails from all rooms!):
-
A first e-mail is sent 10 minutes after you received the first message while offline, or after 10 minutes of not reacting to browser / phone notifications.
-
A second e-mail is sent 10 minutes after the first if there are any new messages since the first one.
-
No new e-mails are sent for the next 12 hours, after which this whole three-step timer process is started again.
4.4. Creating and managing rooms and chats
Creating rooms. It is advisable to always create rooms, even if you only want to chat with one person. For that, click + next to the section title âRoomâ, click âCreate new roomâ and in the settings screen that appears set âEnable end-to-end encryption: offâ. Unlike chats create in section âPeopleâ, rooms allow to disable encryption, so you will not have to deal with cross-device key requests, key backup, inability to read old messages and so on.
The difference of chats created in section âPeopleâ is that these chats treat every message as if it contained a mention, so the person you are chatting with will see the notification of every message you send. However, you can achieve the same in rooms by hovering over the room name in the element.io room list sidebar, clicking on the bell icon, and setting âNotification options: All Messagesâ. That affects only notifications to you, so your chat partner would have to do the same on their side.
Inviting people to a room. Once a room has been created, you will need to invite people to join it. Click on the room from the list on the left, then click the âInvite to this roomâ icon on the bottom right of the window. Invited people appear in a list on the right side of the window. Please note: when you try to invite someone who has not changed their default display name, autocomplete will not work, and you will have to type the whole address as @username:edgeryders.eu
.
Customizing rooms. Click the cog icon next to the room name to change the settings. We recommend to upload a nice avatar for it: you can do so by clicking the camera icon under the avatar (the default avatar is a circle with the first letter of the roomâs name). The camera icon is only visible after clicking on the cog (settings) icon. We also recommend you set a color for the room that is in line with the avatar. This way, people have a visual cue as to which room they are writing in.
Room administration actions. As a roomâs administrator, you have the options to âmuteâ, âkickâ and âbanâ users, also accessible with slash commands of the same name:
-
âMuteâ means the user stays in the room and can read but not contribute any more.
-
âKickâ is forcing a user to leave the room, just as if they had chosen the âleaveâ action by themselves. Means, they can re-join at will (if itâs a public room) or when invited.
-
âBanâ means a forced leave, and the user is prevented from re-joining until the admin uses an âunbanâ command.
Getting more help. The âofficialâ documentation of the Riot client to Matrix, which we use, is here.
4.5. Voice calls, video calls, screensharing
Matrix includes functions for voice and video calls. The one-on-one calls work pretty well, and you can just use them. But the conference calls feature is not mature at all and will not be finished, so we use Zoom and sometimes Google Hangouts for group / team calls etcâŚ
Fixing âCould not connect mediaâ. In case a one-on-one voice or video call does not work for you with an error message âcould not connect mediaâ, try the following:
-
Simply try calling again. Usually, this happens due to intermittent network failures, esp. network congestion, either in the local wifi networks or the WAN / Internet. Otherwise:
-
Donât use Firefox on Mac. Currently (2020-01), voice calls are not possible with the Firefox browser on a Mac OS X operating system. If thatâs your case, switch to Chrome (or Chromium, Ungoogled Chromium or the like) for these calls.
-
Disable P2P connections. Click the lower-left gear icon to go to the user settings screen, and there enable the option âVOPI: Disable Peer-to-Peer for 1:1 callsâ. Both parties of a call have to do this before the call. This should work around firewall issues that can prevent direct connections between computers on the Internet; such issues can happen when you are in a university network or other heavily managed / protected network. (However, this tip is experimental. Tell in the comments below if it helped.)
Screensharing. Matrix / Riot supports screensharing in calls, but like voice and video calls it is only properly usable for one-on-one calls. It works with recent Firefox and Chrome versions like this:
-
If the screen-sharing userâs browser is Chrome (or Chromium), he or she has to start it with a special command line option (details). For example:
chromium-browser --enable-usermedia-screen-capturing
-
In the Riot web application, press the âShiftâ key and then click the videocall button.
-
Confirm you really want to share your screen. (More on screensharing safety.)
More details about this process here. It works well when screen-sharing from Firefox or Chrome, and receiving in Chrome (should also work in Firefox, but it had issues at times).
4.6. Voice messaging
When communicating over a low-bandwidth Internet connection with undependable quality, voice calls in Matrix / Riot or otherwise will not be of much use as it will be hard and often impossibe to understand each other. Here, sending voice messages back and forth in a Matrix chat is a nice solution.
Voice messages are just audio files uploaded from the local computer. Those in formats MP3, OGG and WAV (and perhaps more) will then get an embedded player right in the Matrix chat. For the file format, we here go for Vorbis files (.ogg
) at the lowest quality (0
), which means 64 kbps and results in a file size of ca. 360 kB per minute when using one audio channel. That audio quality is good for voice messages, file size is as well compact.
So we only need an efficient workflow to record and upload these audio files, and weâre good to go â see the instructions below.
Remaining issues. In the setup as documented below, a few issues remain:
-
Navigation in the soundplayer embedded in Riot does not work. Probably a normal bug. You can download and open the file in another soundplayer to fix this.
-
For uploading voice messages or any other files >2 MiB, a configuration change to our Matrix server is needed.
1. Voice messaging under Linux
Installation and configuration:
-
Install audio-recorder (instructions).
-
Start audio-recorder with the command
audio-recorder
. -
In the âAdditional Settings â Generalâ screen, disable âWindow always on topâ.
-
In the âAdditional Settings â Recording Commandsâ screen, create a OGG recording command with:
- Title: âVoice message, lossy, 64 kbpsâ
- File extension: ogg
- Command:
audio/x-raw,rate=44100,channels=1 ! vorbisenc name=enc quality=0.0 ! oggmux
-
Using the corresponding option in your window manager, send the window to a specific desktop to prevent it from showing up on all at once.
-
Create a bookmark in your file opening dialogue for the directory where audio-recorder stores its recordings.
Usage:
-
Make a recording in audio-recorder by pressing start and stop. It is saved automatically.
-
Click the âfile uploadâ dialogue in Riot to upload the recorded file.
-
Use your bookmark to navigate to the directory with the recordings and choose the newest one.
More documentation:
-
For audio-recorder: open this URL in your browser (tested on Ubuntu 17.04):
file:///usr/share/audio-recorder/
. -
For the options of GStreamer vorbisenc, see here.
-
For the quality values of GStreamer vorbisenc: 0.0 - 1.0 correspond to 0 - 10 in the official Vorbis standard â source.
2. Voice messaging under Windows
Installation and configuration:
-
Visit the Github project âInstruction Guide: fmedia under Windowsâ.
-
Download the project as a
.zip
file, as shown here:
-
To unpack, install and use the software, follow the installation and usage instructions in the projectâs README.
4.7. Sharing login credentials and other secrets
The advised and safest way to share login information of Edgerydersâ accounts for external platforms (e.g. GMail, Twitter, Zoom) is to send it in Riot as follows:
-
Make sure receiving party is on the Edgeryders Matrix server: mouse over their avatar to show the address and make sure the address ends in
:edgeryders.eu
. -
Start a personal one-on-one chat for this purpose.
-
Enable encryption for this chat in the chatroomâs settings.
-
Send the login credentials or other secret information.
-
Remove the message after the other party confirms they got it. You find that option in the
âŚ
menu of a message, which appears when mousing over it.
In fact this mechanism is much safer than sending a password by (unencrypted) e-mail: it is encrypted by HTTPS and by end-to-end encryption, stored in encrypted form, and is deleted after use from our server, with no copies ending up on other servers. (The latter is why this process should only be used for @username:edgeryders.eu
Matrix IDs.)
4.8. Resetting your password
Due to the way how our Matrix server is set up right now, your Matrix ID is independent of your e-mail address. You also cannot connect it to your e-mail address yourself â the corresponding feature under âuser menu â All Settings â E-Mail Adressesâ simply does not work.
Consequentially, you cannot reset your own password. Ask @matthias to do so if you need it reset.
4.9. Other tips and tricks
Fixing online status issues. If you see somebody posting while they are shown as âofflineâ in your Riot applicationâs sidebar, it is usually because they are posting from a device you did not verify. Click on their user avatar icon, and verify the device they are currently using, or all devices. Do it either âthe right wayâ (confirming in a voice call that the keys match), or just click âverifyâ if you donât care about encryption integrity in this chat.
Slash commands. Similar to good old IRC, Matrix supports some commands. With the âNew Composer & Autocompleteâ enabled in your account settings, type a slash â/â at the beginning of a message, and choose from the proposed commands. Most are useful for admins only. The riot.im/app/ stable version provides 8 commands at this time, while the riot.im/develop/ development version has 19.
Using the Riot.im âdevelopâ version. While riot.im/app/ provides the main / stable version of the Riot software, there is also a development version available at riot.im/develop/. It will share a login with the main / stable version, so you can use both in parallel without having to log in again. The develop version is always some days or weeks newer than the main / stable version, so some bugs will be removed and perhaps some new ones will be introduced. Use if youâre an optimist
5. Edgerydersâ Matrix addressbook
Currently, the following accounts exist on our Matrix server (and some more, but just because this list needs some updating âŚ):
- @alberto:edgeryders.eu
- @amelia:edgeryders.eu
- @anthony_di_franco:edgeryders.eu
- @anu:edgeryders.eu
- @bob:edgeryders.eu
- @bachar_khattar:edgeryders.eu
- @bojanbobic:edgeryders.eu
- @clairedvn:edgeryders.eu
- @daniel:edgeryders.eu
- @hugi:edgeryders.eu
- @indy:edgeryders.eu
- @ivanv:edgeryders.eu
- @jean_russell:edgeryders.eu
- @johncoate:edgeryders.eu
- @luca_mearelli:edgeryders.eu
- @lylycarrillo:edgeryders.eu
- @mariacoenen:edgeryders.eu
- @mariaeuler:edgeryders.eu
- @marina:edgeryders.eu
- @markomanka:edgeryders.eu
- @martin:edgeryders.eu
- @matteo_uguzzoni:edgeryders.eu
- @matthias:edgeryders.eu
- @nadia:edgeryders.eu
- @noemi:edgeryders.eu
- @owen:edgeryders.eu
- @thomasmboa:edgeryders.eu
- @trythis:edgeryders.eu (thatâs Sam)
- @webmaster:edgeryders.eu (special, not conforming to anyoneâs edgeryders.eu account)
- @zmorda:edgeryders.eu