Getting Started feedback about amazon-chime-sdk-js

[RossWilliams]

The top method lacking documentation and which burned countless hours in frustration is AudioVideoController.start()

The main reason is start() must be called after setting up audio. Calling start() before binding audio will cause realtime observers to not pick up on volume level changes. Documenting this method is critical.

Other issues around start():

• It has zero documentation
• It is briefly mentioned in the getting started guide. Unfortunately the README.md file has a broken link to the getting started guide.
• start() calls actionConnect, a god method with over 100 lines and more than 30 objects created. It is doing an incredible amount of work, but other than a line in the getting started guide to call it, there is no indication to the user how important this method is.
• the demo app calls start() twice, both in the constructor and form submit handler. Why does it need to be called twice?
• the DefaultAudioVideoController has few code comments, and none which help to understand the code.
• the facade where start is defined isn't commented either.

[andibrae-amzn]

@RossWilliams and others who have shared their feedback on this thread, thank you very much for your in-depth critique of the SDK documentation. I want you to know the team hears you, and clearly we have a lot of work to do to simplify onboarding and make the library easier to understand. We have created GitHub issues (referenced above this comment) from the concerns enumerated in the comments.

The team is working to prioritize these issues. We plan to first tackle issues that are emblematic of the concerns raised so far (e.g. #208, #217, #209, #229, and other issues that can be addressed quickly).

We will leave this issue open for now to keep the conversation going. Feel free to open specific issues with the documentation issue template.

[Aarondorn2]

I agree the documentation here could use some more information. Here's the path I followed in case it can help you:

• Spent time researching the WebRTC standard. here's a good resource: https://www.frozenmountain.com/ultimate-guide-to-webrtc
• Originally implemented a different solution (I hadn't heard of Chime) called TokBox by Vonage; their API is a little more user-friendly and their docs are great. Their price is absurd - after implementing I was given a link from them explaining they charge N * (N -1) * minutes. A 30 minute meeting with 4 people is 4 * (4-1) * 30 = 360 minutes. I've reached out to AWS to confirm, but have understood Chime's model to be N * minutes.
• Switched the implementation to Chime using the following docs, videos, and reading through the demo app.

I spent probably 5-10 hours on researching WebRTC, 20-30 on TokBox and UI, then about 10 (so far) on Chime. I'm still adding some polish, but have enough to facilitate a meeting with any number of participants.

[juanpaie]

I definitely agree on this. We're currently integrating Chime SDK and documentation needs to be more simple, explaining concepts and providing a quickstart guide with more demos not only using native Javascript but also using React, Vue.js and Angular.

[Aarondorn2]

Yesterday I was hung up on managing the 'roster'. I had built off of the videoTileDidUpdate and videoTileWasRemoved observers, but removed also triggers when a participant disables their own video, which makes sense. If a participant disabled their video, it looked like they left the meeting, even if they were still contributing audio.

I had to dig through the API docs to find audioVideo's realtimeSubscribeToAttendeeIdPresence and combine that with the other hooks to keep track of who's in the meeting and which of those attendees are contributing video.

It seems inconsistent that the attendee presence is a direct function call on audioVideo and not part of the AudioVideoObserver as the videoTile functions are.

[andibrae-amzn]

To follow up on a couple specific points:

the demo app calls start() twice, both in the constructor and form submit handler. Why does it need to be called twice?

The meeting demo only calls audioVideoFacade.start() here in the join() method. Point taken though that there are other places where the method name start is used in the demo, which is confusing.

I've reached out to AWS to confirm, but have understood Chime's model to be N * minutes.

Yes, billing is per attendee connection minute. For more information on Chime SDK pricing, see here.

[mding5692]

Following this topic as well, AWS Chime reached out to our company recently to integrate AWS Chime SDK into our company's web app. Would like to see some kind of specific quickstart guide similar to how Twilio Video API does it.

[andibrae-amzn]

We have published an API overview (#209) that steps through the main API objects and methods involved in starting an audio and video meeting with a roster. Feedback is welcome:

https://aws.github.io/amazon-chime-sdk-js/modules/apioverview.html

We continue to prioritize our efforts on #208, #217, #229 and have also closed a few of the more minor issues #218, #221, #222.

[RossWilliams]

Other comments for the demo app:

1. Using the whole DemoMeetingApp class as the observer for various controllers makes understanding the demo harder. An improvement would be to comment the methods used for each observer and group them together. Delegate patterns like this can make sense when users routinely interact with an interface and can easily recognise method names, but for a demo to help understand concepts it does not seem like a good strategy.
2. videoTileDidUpdate appears to be a critical method to implement, but it is only mentioned in the content share section. It is also poorly named, as it also handles create events. But what this really needs is documentation to state why a video tile would be created or updated, and how can a person work with a video tile.

[RossWilliams]

@aburnson I wasn't confused about naming. I know audioVideoFacade.start()is in the codebase once in the join method, but join is called in both the constructor here and later in form submit handler here. So in the demo app when going through the flow the start() method will be invoked twice. Also, i'm not sure why you need to call it a second time inside a setTimeout wrapper function?

[andibrae-amzn]

@aburnson I wasn't confused about naming. I know audioVideoFacade.start()is in the codebase once in the join method, but join is called in both the constructor here and later in form submit handler here. So in the demo app when going through the flow the start() method will be invoked twice. Also, i'm not sure why you need to call it a second time inside a setTimeout wrapper function?

I see what you mean now. We recently added a record mode where the demo will automatically join without any interaction so that the client can be recorded. The amazon-chime-sdk-recording-demo sample that we just released makes use of this mode to show how a meeting can be recorded with a headless browser running in ECS. The join in the constructor is for the non-interactive recording mode (where a meeting bot joins programmatically) and the join in the form submit handler is for the regular interactive flow where a user would set up devices before entering the meeting.

[Aarondorn2]

Thank you @aburnson & team! I really appreciate your hard work - I know you've been extra busy lately.

[andibrae-amzn]

I'm going to go ahead and close out this thread now. We have resolved a number of the individual issues identified here: #207 #209 #212 #213 #214 #215 #217 #218 #221 #222 #227 #228.

We are tracking and working to prioritize the remaining issues with the documentation label:
https://github.com/aws/amazon-chime-sdk-js/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation

Thanks again everyone for all the feedback!

[RossWilliams]

Thanks, the documentation looks great now. Hard to look at it with fresh eyes, but it should give people a lot of confidence picking up the library.