netless-io / flat

Project flat is the Web, Windows and macOS client of Agora Flat open source classroom.

Agora Flat

Project flat is the Web, Windows and macOS client of Agora Flat open source classroom.

中文

Features

• Real-time interaction
  • Multifunctional interactive whiteboard
  • Real-time video/audio chat (RTC)
  • Real-time messaging (RTM)
• Login via
  • GitHub
  • WeChat
• Classroom management
  • Join, create and schedule classrooms
  • Support periodic rooms
• Classroom recording and replaying
  • Whiteboard replaying
  • Cloud recording for video and audio
  • Messaging replaying
• Cloud Storage for multi-media courseware
• Screen sharing

Quickstart

You can build and run the Flat client without a server. This repository includes the following projects:

• Flat Electron client is an Electron implementation of Flat client.
• Flat Web client is a web implementation of Flat client.

Installation

If you don't have pnpm installed:

npm i -g pnpm

Clone or fork this project, at project root run:

pnpm i

Build and run Flat Electron client

Run the following commands at the root of the repository to build and run Flat Electron client.

pnpm start

You can use one of the following methods to package your executable:

• Run pnpm ship at project root to package based on current system.
• Alternatively, run pnpm ship:mac or pnpm ship:win at project root to package for a specified system.

Build and run Flat Web client

Run the following command at the root of the repository to build and run Flat web client.

pnpm start:web

Alternatively, run the following command:

cd ./web/flat-web/ && pnpm start

UI and business logic are separated in Flat. You can view and develop Flat components UI via Storybook. You can either visit the (Online address) or run pnpm storybook at the root of the repository to run Storybook locally.

References

• Release Version Description
• Environment Variables Reference
• Debugging Flat

Related Projects

• Flat Android client
• Flat Server
• Flat Website HomePage

Contributing

Writing code is great, but there are many other ways to make meaningful contributions to the project:

• Improve documentation
• Improve issues
• Give feedback on issues

For more info about how to contribute, see CONTRIBUTING.md

Code Contributors

Thank you to all the people who already contributed to Flat!

Disclaimer

You may use Flat for commercial purposes but please note that we do not accept customizational commercial requirements and deployment supports. Nor do we offer customer supports for commercial usage. Please head to Flexible Classroom for such requirements.

License

Copyright © Agora Corporation. All rights reserved.

Licensed under the MIT license.

When using the Flat or other GitHub logos, be sure to follow the GitHub logo guidelines.

flat's Issues

[bug]: blocking browser fallback in flat-web

when accessing https://flat-web.whiteboard.agora.io/ from another page in the browser, the browser will not be able to make the action that will rewind to the previous page.

[bug]: error was reported after joining the room

[refactor]: `INVITE_BASEURL` does not meet the semantics in flat-web

INVITE_BASEURL Does not meet the semantics

Originally posted by @BlackHole1 in #829 (comment)

https://github.com/netless-io/flat/pull/834/files#diff-80cd6ff40d48acb0207a9e0780233787449517800f219c43a5d83f1569b344d1R95

[BUG]: Better to list iTerm as a prerequisite for macOS developers

macOS developers will encounter a script error when running the project with yarn run start if iTerm is not installed. Better to list this as a prerequisite. Otherwise, the startup experience may not smooth for some developers.

Pause room status can't resume

After click pause button, resume not working.

question(web): run start failed

I was working on the flat-web module but eventually got some error

Can anyone suggest how to resolve the error

[bug]: resolve load source-map error

Reproduce Step

1. open flat
2. open devtools at renderer
3. switch console
4. (option) click WeChat Login button:
   

Note

launch Flat when development environment:

if click weChat Login button:

---

if open the release Flat:

if click weChat Login button:

[feat]: permission request requires i18n support in macOS

see:

flat/desktop/main-app/electron-builder.yml

Lines 21 to 22 in 2b89c56

	NSMicrophoneUsageDescription: To ensure normal use, flat-native needs access to your microphone.
	NSCameraUsageDescription: To ensure normal use, flat-native needs access to your camera.

we need support Chinese desc

[improve]: show errortips only once

After opening https://flat-web.whiteboard.agora.io, switch to another tab page.

At this time, if you are in a situation where you have no internet, or very poor internet. Wait a few minutes and switch back to the flat page.

You can then see a very large number of repeated error messages.

But really we only need it once.

CleanShot.2021-12-06.at.14.55.34.mp4

[bug]: flat-web failed to startup

The web terminal failed to start, any good suggestions?

[chore]: support github actions reusable workflows

github blog: https://github.blog/2021-11-29-github-actions-reusable-workflows-is-generally-available/

We can encapsulate workflows that are duplicated in existing actions to facilitate maintenance at a later stage.

Because the problem now is that many of our workflows are duplicated and more difficult to maintain.

[refactor]: add object-curly-newline rule in eslint

To keep the code style uniform, we need this rule

rule details: https://eslint.org/docs/rules/object-curly-newline

You should add this rule to eslintCommon -> base -> rules in .eslint.common.js. eg:

flat/.eslint.common.js

Lines 133 to 134 in ef6668b

	semi: ["error", "always"],
	"@typescript-eslint/explicit-module-boundary-types": "off",

just like this:

[refactor]: adjustment of file name specification

Since we don't do any strong checks on the file names, we have the following file name forms:

1. camelcase
2. snake_case
3. kebab-case
4. Pascalcase

I think we should have a set of specifications to restrict file names.

all I can think of at the moment is:

• Components: Pascalcase
• script: kebab-case
• other: camelcase

[refactor]: download url should placed in env

Originally posted by @BlackHole1 in #810 (comment)

[bug] room tips display level too high

Reproduce Step

1. Create room
2. (automatic) Join room
3. Open Cloud storege

Expected behavior

room tips z-index < Cloud Storage z-index

yarn install error

Environment: Mac Big Sur
Node: v16.0.0
NPM: v7.10.0
Yarn: v1.22.10

and

Environment: Windows 10
Node: v14.15.4
NPM: v6.14.10
Yarn: v1.22.10

yiwen@YIWENtekiMacBook-Pro flat % yarn install --frozen-lockfile
yarn install v1.22.10
$ node ./scripts/preinstall
[1/4] 🔍  Resolving packages...
[2/4] 🚚  Fetching packages...
error Couldn't find match for "fb67b54fe18bdf556fb3e3d00db5fbaf0dbb294d" in "refs/heads/dependabot/npm_and_yarn/electron-9.4.0,refs/heads/dependabot/npm_and_yarn/ini-1.3.8,refs/heads/dependabot/npm_and_yarn/lodash-4.17.19,refs/heads/dependabot/npm_and_yarn/npm-6.14.6,refs/heads/dependabot/npm_and_yarn/npm-registry-fetch-4.0.5,refs/heads/dependabot/npm_and_yarn/npm-user-validate-1.0.1,refs/heads/fix-electron-warning,refs/heads/master,refs/tags/v1.0.0,refs/tags/v1.0.1,refs/tags/v1.0.2,refs/tags/v1.0.3,refs/tags/v1.0.4,refs/tags/v1.0.5,refs/tags/v1.1.0,refs/tags/v1.1.1,refs/tags/v1.1.2,refs/tags/v1.1.3,refs/tags/v1.1.4,refs/tags/v1.1.5,refs/tags/v2.0.0,refs/tags/v2.0.1,refs/tags/v2.1.0,refs/tags/v2.2.0,refs/tags/v2.2.1,refs/tags/v2.2.2,refs/tags/v2.2.3,refs/tags/v2.2.4,refs/tags/v3.0.0,refs/tags/v3.1.0,refs/tags/v3.1.1" for "git://github.com/BlackHole1/electron-devtools-installer".
info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command.

[bug]: mouse cannot be displayed during screen sharing on desktop

[discussion]: desktop/renderer-app

• Need vite electron plugin support
• Need ESLintPlugin
• Need BundleAnalyzerPlugin support ,use Rollup Plugin Visualizer
• Need process.env support
• Need support fs-extra
• Need support extract-zi

[bug]: whiteboard text tool can not typing on mobile device

I thought it should be popup the keyboard for me to input the text, but it doesn't

Reproduction steps
Click on whiteboard with text tool

Device
iPad 15.1、iPhone 14.8

Browser
chrome、safari

Dart is more suitable alternative

Dart is an object-oriented C language，Dart is a statically typed language that eliminates common sources of errors in JavaScript code. Dart supports type inference, so there is no need to include type boilerplate every time a variable or function is declared.Perhaps the most exciting feature of Dart is its availability outside the network.Perhaps the most exciting feature of Dart is its availability outside the network. Google's Flutter UI toolkit is a portable front-end framework that can be used on desktops, mobile devices and the Web to build native applications. @bestony

[bug]: Nav does not need to re-render, when switching tab

End
flat-web

What steps will reproduce the problem?

1. open flat-web link, and login
2. switch tab
3. nav will be re-rendered

What is the expected result?
When switching tab, nav does not need to re-render

keep packages/flat-types build with tsc

Using vite to build ts is not a good idea，detail see https://vitejs.dev/guide/features.html#typescript

[pref]: SVGs need to be optimized.

SVGs need to be optimized.

You can try with SVGO.

Originally posted by @LitoMore in #1145 (comment)

[bug]: autoResize not scaling

Im finding that autoresize scaling is not adjusted when adjusting the whiteboard div. Sometimes it works but most of the time it doesn't.

I believe the issue is due to the ApplianceManager.GetViewState() returning 0 for width and 0 for height. When the adaptRectangle is created it forces a scale of 1.

when refreshSize is called this.adaptRectangle is null which forces the resize property to take this.camera property.

is this a race condition as the DIV container is not yet created so the Width and Height is 0?

below is excerpts of white-sdk

creation of adaptRectangle below

  key: "adaptRectangle",
          value: function adaptRectangle(e) {
              if (e.width === 0 || e.height === 0) this.transformCamera({
                  animationMode: e.animationMode,
                  centerX: e.originX + e.width / 2,
                  centerY: e.originY + e.height / 2,
                  scale: 1
              });
              else {
                  var t = He(D({}, this.cameraWithAdaptRectangle(e, e.adapterMode)), {
                      animationMode: e.animationMode
                  });
                  this.setCameraTransfrom(t, !1), this.adaptedRectangle = Object.freeze({
                      originX: e.originX,
                      originY: e.originY,
                      width: e.width,
                      height: e.height,
                      adapterMode: e.adapterMode
                  })
              }
          }
        },

this.adaptedRectangle is null and therefore this.camera properties are taken.

key: "refreshSize",
        value: function refreshSize(e, t) {
            if (this._width !== e || this._height !== t) {
                this._width = e, this._height = t;
                var r;
                this.adaptedRectangle ? r = this.cameraWithAdaptRectangle(this.adaptedRectangle, this.adaptedRectangle.adapterMode) : r = this.camera, this.setCameraTransfrom(He(D({}, r), {
                    animationMode: G.Immediately
                }), !1), this.dispatchUpdatedEvent(r, !1), this.sizeUpdatedDispatcher.dispatch({
                    width: e,
                    height: t
                })
            }
        }

[chore]: remove superfluous comment

The following comments are redundant and can be removed. If there are other redundant comments, they can also be deleted together.

flat/web/flat-web/src/constants/process.ts

Line 34 in a2ed313

// TODO: english version is WIP

[refactor]: activate terminal after start command

exec yarn run start in project root path, will open system terminal or iTerm2.
but they(terminal / iTerm2) will not to the front (like z-index).

1.mp4

related documents: https://developer.apple.com/library/archive/documentation/AppleScript/Conceptual/AppleScriptLangGuide/reference/ASLR_cmds.html#//apple_ref/doc/uid/TP40000983-CH216-SW60

related code:

• flat/scripts/launch/mac/launch_iTerm.scpt

  Lines 1 to 10 in 63b14ae

  	tell application "iTerm"
  	set W to create window with default profile
  	tell W's current session
  	split vertically with default profile
  	end tell
  	set T to W's current tab
  	set ProjectRoot to "$(dirname $(dirname $(dirname $(dirname " & (POSIX path of (path to me)) & "))))"
  	write T's session 1 text "yarn --cwd \"" & ProjectRoot & "/desktop/renderer-app\" start"
  	write T's session 2 text "yarn --cwd \"" & ProjectRoot & "/desktop/main-app\" start"
  	end tell

• flat/scripts/launch/mac/launch_terminal.scpt

  Lines 1 to 5 in 63b14ae

  	tell application "Terminal"
  	set ProjectRoot to "$(dirname $(dirname $(dirname $(dirname " & (POSIX path of (path to me)) & "))))"
  	do script "yarn --cwd \"" & ProjectRoot & "/desktop/renderer-app\" start"
  	do script "yarn --cwd \"" & ProjectRoot & "/desktop/main-app\" start"
  	end tell

[chore]: add optimization svg git hook

Add optimization svg script in git hook.

Like: https://github.com/birjolaxew/svglint

Related PR: #1152

cc: @LitoMore

[pref]: refactor date-fns import/use

In the project, I found that we were mixing up the data-fns approach, which would result in less maintainable code and no Tree shaking, eg:

import { format } from "data-fns/fp";
import { add } from "data-fns";
import max from "data-fns/max"

After testing, I found that I should change the data-fns to:

import format from "date-fns/fp/format";
import addBusinessDays from "date-fns/fp/addBusinessDays";

we should use fp, unless the method does not exist in fp

This is for code maintainability reasons

---

I tested several different writing methods to analyze their final pack size

mix use deconstruction

import { format } from "date-fns";
import { addBusinessDays } from "date-fns/fp";

Stat Size: 625.18 KB

use deconstruction

import { format } from "date-fns/fp";
import { addBusinessDays } from "date-fns/fp";

Stat Size: 582.38 KB

mix use no deconstruction

import format from "date-fns/format";
import addBusinessDays from "date-fns/fp/addBusinessDays";

Stat Size: 91.98 KB

use no deconstruction

import format from "date-fns/fp/format";
import addBusinessDays from "date-fns/fp/addBusinessDays";

Stat Size: 92.21 KB

---

From the above, we can see that there is not much difference between mix use no deconstruction and use no deconstruction. The reason why use no deconstruction is a bit larger than mix use no deconstruction is that there is more code for fp implementation.

As I mentioned above, we should only use one for code maintainability (usually fp's methods are sufficient for our needs)

Another reason to choose fp is that we can take advantage of Currying for further abstraction.

control scale api

Did you solve the problem of controlling scaling API mentioned before

Join Slack

Join Link 👉 Agroa Flat Slack

if the link does not work, please leave a comment and we will update it

[discussion]: Questions about the open-source of this project

感谢你们的开源，想咨询一下这是基于声网传输服务的收费开源项目吗？

Update (i18n)

Thank you for the open source, I would like to inquire about this is based on the sound network transmission service fee open source project?

[refactor]: remove Chinese comment

remove all Chinese comment in project, replace with English.

Because this project is open to all developers worldwide, we should use English as the primary language for ease of communication and maintenance

match Regex: (//|\* ).*[\u4e00-\u9fa5]
file type: *.ts,*.tsx,*.json,*.js.

e.g:

[bug]: Teacher side end hand up, student side microphone is not turned off

Overview of the problem:

1. start class
2. students raised their hands and then spoke
3. the teacher clicked to end but the students’ microphones were still ringing

Expected behavior:
Teacher clicks to end, student's microphone is turned off

Actual behavior:
Teacher clicks to end, student's microphone is not turned off

@bestony

[chore]: remove shelljs library

We don't really need shelljs as a library to do something for us.

There is no need to install another library to solve the problem as we can write some tools to replace it.

flat/package.json

Line 35 in a2ed313

"shelljs": "^0.8.4"

flat/desktop/main-app/scripts/agora/mv-addon.js

Line 7 in a2ed313

shelljs.mv(path.join(mainPath, "build"), path.join(agoraElectronSdkPath, "build"));

remove shelljs command:

# Project root path
yarn remove shelljs -W

[refactor]: remove useless code / file / dependencies

for historical reasons there are code that we will never use again and we should delete them instead of keeping them in the project.

e.g:

1. /desktop/renderer-app/src/taskUuids.ts
2. /desktop/renderer-app/src/custom.d.ts
3. /desktop/renderer-app/src/react-app-env.d.ts
4. /desktop/renderer-app/package.json -> scripts -> react-app-rewired and eject
5. /desktop/renderer-app/package.json -> devDependencies -> edit-json-file
6. ...

[chore]: replace react router custom loop by offical api

Implementation of using useroutes instead of https://github.com/netless-io/flat/blob/main/web/flat-web/src/AppRoutes/index.tsx#L15

cc @BlackHole1 @hyrious @LitoMore

[bug]: Virtual webcam not showing on desktop

Unable to choose virtual webcam on Mac OS. The only camera in the list is the default built-in webcam. The web version of flat has the virtual camera available in the dropdown menu.

Where to find the development documentation？

Where to find the development documentation？

[Feature Request] Screen Sharing

Is it possible to add screen sharing

[chore]: replace rollup with webpack

flat-web use rollup, but rollup has high memory requirements.

The disadvantages of rollup outweigh its advantages.

If the memory problem is solved by a later rollup, we will consider migrating it all.

But for now we need to use webpack.

Remove component code from store

Use a property to switch Preview Modal:

flat/desktop/renderer-app/src/pages/CloudStoragePage/store.tsx

Lines 382 to 390 in f9f9932

	Modal.info({
	content: <ResourcePreview fileInfo={fileInfo} />,
	className: "resource-preview-container",
	width: "100%",
	centered: true,
	closable: true,
	maskClosable: true,
	closeIcon: <img src={closeSVG} />,
	});

Style files should be alongside with the component:

flat/desktop/renderer-app/src/pages/CloudStoragePage/store.less

Line 1 in f9f9932

.resource-preview-container {

[discussion]: vite is ready for storybook?

In https://github.com/netless-io/telebox-insider vite is ready for storybook

[bug]: electron → web RECV_VIDEO_DECODE_FAILED

When use mode: 'live' (or broadcast in electron), you can't see the video stream sent by electron on the web page, other directions are ok.

I will investigate it soon.

Update: did not reproduce on windows x64 with agora-electron-sdk@latest

[chore]: replace esbuild with swc in flat-web

Our mobx class is starting to look more and more complex. Using reflect-metadata can be a good solution to this problem.

currently flat-web uses vite, and uses vite's built-in esbuild build tool.

But currently esbuild does not support reflect-metadata, which is the main reason why we want to migrate to swc.

Since the implementation logic of esbuild and swc is completely inconsistent, it will be difficult to support esbuild in the future, see: evanw/esbuild#257 (comment)

Related Links: vitejs/vite#788

[bug]: run dekstop failed on windows system

Environment

Windows 10

Steps to reproduce

After executing yarn run start.

The following error occurs:

C:\Users\WL\Documents\GitHub\flat\node_modules\electron\dist\electron.exe exited with signal SIGINT

(node:1656) ExtensionLoadWarning: Warnings loading extension at C:\Users\WL\AppData\Roaming\Electron\extensions\fmkadmapgofadopljbjfkapdkoienihi: Unrecognized manifest key 'browser_action'. Unrecognized manifest key 'minimum_chrome_version'. Unrecognized manifest key 'update_url'. Cannot load extension with file or directory name _metadata. Filenames starting with "_" are reserved for use by the system.

Checking for update
Update for version 11.3.0 is not available (latest version: 1.1.0-beta.1, downgrade is disallowed).

Checking for update
Update for version 11.3.0 is not available (latest version: 1.1.0, downgrade is disallowed).

The app launches successfully with errors and I can neither create nor join a room:

[refactor]: improve i18n keys

I feel that the names of many keys are not unique enough, do we need to introduce the concept of namespace. @Leooeloel @crimx

e.g:

i-know => i-know-extra-countdown

(namespace name)room-exit:
    i-know

Originally posted by @BlackHole1 in #662 (comment)

[chore]: use `unicorn/filename-case` eslint rule

Previously, we discussed the specification of file names (see: #714)

But this is all built on an ego-driven basis and we need to have a rule to help us check this.

Thanks to @LitoMore recommendation, we were made aware of the existence of unicorn/filename-case.

Rule Link: https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/filename-case.md

The following rules, which I have just come up with, may not be perfect.

"unicorn/filename-case": [
	"error",
	{
		"cases": {
			"kebabCase": true,
			"ignore": [
				"^[A-Z].+\\.tsx$",
				"^README.*\\.md$",
				".*\\.yaml",
				".*\\.yml"
			],
		}
	}
]

refactor agora api schema type

Originally posted by @BlackHole1 in #25 (comment)

[chore]: unified build tool to vite

The current flat sub-project uses a different build tool:

• #1300
  • webpack assign to @Cyberhan123
• #1173
  • webpack assign to @Cyberhan123
• web/flat-web
  • vite (esbuild + rollup)
• #1143
  • webpack (storybook built-in) assign to @Cyberhan123
• #1131
  • tsc assign to @Cyberhan123

we always knew it was confusing, but the good news is that we will remain unified in the future and will all switch to vite.

before switching to vite, we need to wait for the storybook to support vite builds

The storybook is still being optimized and there are still some issues with storybook-builder-vite(see:
storybookjs/builder-vite#2).

When they are finished, they will be ready for migration

other sub-projects can be migrated in one step first

[chore]: use typescript language re-write scripts

As JavaScript is not as easy to maintain later as TypeScript, we intend to rewrite it using TypeScript. Runtime environments can be used: ts-node etc. If you have a better idea, please let us know.

cc: @hyrious @LitoMore