joystream/atlas

Whitelabel consumer and publisher experience for Joystream

Joystream

This is the main code repository for all Joystream software. In this mono-repo you will find all the software required to run a Joystream network: The Joystream full node, runtime and all reusable substrate runtime modules that make up the Joystream runtime. In addition to all front-end apps and infrastructure servers necessary for operating the network.

Overview

The Joystream network builds on the substrate blockchain framework, and adds additional functionality to support the various roles that can be entered into on the platform.

Development

For best results use GNU/Linux with minimum glibc version 2.28 for nodejs v18 to work. So Ubuntu 20.04 or newer.

You can check your version of glibc with ldd --version

The following tools are required for building, testing and contributing to this repo:

• Rust toolchain - required
• nodejs >= v14.18.x - required (However volta will try to use v18.6)
• yarn classic package manager v1.22.x- required
• docker and docker-compose v2.20.x or higher - required
• ansible - optional

If you use VSCode as your code editor we recommend using the workspace settings for recommend eslint plugin to function properly.

After cloning the repo run the following to get started:

Install development tools

./setup.sh

If you prefer your own node version manager

Install development tools without Volta version manager.

./setup.sh --no-volta

For older operating systems which don't support node 18

Modify the root package.json and change volta section to use node version 16.20.1 instead of 18.6.0

"volta": {
    "node": "16.20.1",
    "yarn": "1.22.19"
}

Run local development network

# Build local npm packages
yarn build

# Build joystream/node docker testing image
RUNTIME_PROFILE=TESTING yarn build:node:docker

# Start a local development network
yarn start

Software

Substrate blockchain

• joystream-node
• runtime
• runtime modules

Server Applications - infrastructure

• Storage Node - Media Storage Infrastructure
• Query Node
• Distributor Node

Front-end Applications

• Pioneer v2 - Main UI for accessing Joystream community and governance features
• Atlas - Media Player

Tools and CLI

• joystream-cli - CLI for community and governance activities

Testing infrastructure

• Network integration - Joystream network integration testing framework

Running a local full node

git checkout master
WASM_BUILD_TOOLCHAIN=nightly-2022-11-15 cargo build --release
./target/release/joystream-node -- --pruning archive --chain joy-mainnet.json

Learn more about joystream-node.

A step by step guide to setup a full node and validator on the Joystream main network, can be found here.

Pre-built joystream-node binaries

Look under the 'Assets' section:

• Ephesus release v8.3.0

Mainnet chainspec file

• joy-mainnet.json

Integration tests

# Make sure yarn packages are built
yarn build

# Build the test joystream-node
RUNTIME_PROFILE=TESTING yarn build:node:docker

# Run tests
yarn test

Contributing

We have lots of good first issues open to help you get started on contributing code. If you are not a developer you can still make valuable contributions by testing our software and providing feedback and opening new issues.

A description of our branching model will help you to understand where work on different software components happens, and consequently where to direct your pull requests.

We rely on eslint for code quality of our JavaScript and TypeScript code and prettier for consistent formatting. For Rust we rely on rustfmt and clippy.

The husky npm package is used to manage the project git-hooks. This is automatically installed and setup when you run yarn install.

When you git commit and git push some scripts will run automatically to ensure committed code passes lint, tests, and code-style checks.

During a rebase/merge you may want to skip all hooks, you can use HUSKY_SKIP_HOOKS environment variable.

HUSKY_SKIP_HOOKS=1 git rebase ...

RLS Extension in VScode or Atom Editors

If you use RLS extension in your IDE, start your editor with the BUILD_DUMMY_WASM_BINARY=1 environment set to workaround a build issue that occurs in the IDE only.

BUILD_DUMMY_WASM_BINARY=1 code ./joystream

Authors

See the list of contributors who participated in this project.

License

All software under this project is licensed as GPLv3 unless otherwise indicated.

Acknowledgments

Thanks to the whole Parity Tech team for making substrate and helping in chat with tips, suggestions, tutorials and answering all our questions during development.

atlas's Issues

Full UI/UX review

Both to identify new issues, and to add to the list of issues that require designer help to solve.

Carousel alternative on mobile

Carousel alternative on mobile

The current design uses a number of carousels to present content on the landing page. It makes sense for desktop but I don't think that's ideal for mobile.

In the mobile view, most probably only one video will fit the screen at the time. This means that to browse a carousel containing 20 elements, user will need to tap the screen 19 times, to browse items one by one. This probably discourages exploration and makes the UX harder.

For this reason, I think we should find some alternative better fitting mobile view

Originally posted by @kdembler in https://github.com/Joystream/joystream/issues/1245#issuecomment-688211916

Design Brief: Atlas Publisher Experience

Atlas Publisher Experience

Background

We are currently building Atlas, the video consumption product for Joystream, as part of an ongoing release, based on these designs

https://www.figma.com/proto/rBjfm2tJ2Pr9M0UNTduU9v/Joystream-Atlas?node-id=1037%3A1082&scaling=min-zoom

and this component library

https://www.figma.com/file/rBjfm2tJ2Pr9M0UNTduU9v/Joystream-Atlas?node-id=0%3A1

Goal

Currently, there is not product experience for the publisher side of the Joystream. Publishing involves a number of activities, such as

1. Creating new channels.
2. Publishing new content under a channel.
3. Managing metadata associated with existing content.
4. Managing channel metadata.
5. Viewing analytics and statistics relevant to content and channel.
6. Managing monetisation policies.
7. +more

We do not aim to capture the full set of activities described above in this first design, nor model what we do capture to the most detailed and ambitious level. The main goal is to create an initial design which expands Atlas to

a) deal with fundamental interactions such as dealing with the storage system and blockchain.

b) accommodate future scope growth.

c) unlock a few very high value activities, namely 1-4 above, and only with videos. In the future we will also have playlists, episodic videos, and other forms of media.

Domain

In what follows we attempt to describe how the underlying domain of content publishing works in this first version.

Account Management

Any user initiated action on the blockchain requires submitting a transaction, and such transactions require signatures that correspond to accounts with funds. Since publishing requires submitting transactions, Atlas will require some means of managing accounts, funds and transaction signing.

The approach to be taken is the same as the one described here for the Pioneer 2 project

https://github.com/Joystream/joystream/issues/1455

Be aware that for the current state of Atlas, the consumer experience does not require the user have a wallet or funds, it is only for the publisher side this is relevant.

External Images

User provided images are a critical part of the metadata required to deliver the consumer experience in Atlas. This includes images for things avatars, covers for channels and video previews. The platform does not currently store any of these images, they are only represented as HTTP URLs to external storage locations. This will likely change in the future, so the Joystream infrastructure stores all metadata, but currently we face this constraint. Moreover, we want people to be able to just use existing resources, without having to do local image cropping, resizing and lastly uploading. For this reason, the Joystream metadata for each image includes cropping and resizing information, called display information. The structure of the display information depends on how the image is to displayed, below we cover two cases: rectangular and circular

If no image is found at the external location described in the metadata, or if the display information is not compatible with the dimensions of the image found, then some sort of handling will be done in the consumer experience. This could either be ignoring the content wholesale, or displaying some graceful placeholder image.

Rectangular Display Information

Assumes pixels are 0 indexed, W = pixel width of source image, H = pixel height of source image.

• Left
  • Description: Left hand side horizontal pixel offset in source image for what to include in display.
  • Min: 0.
    • Max: W - 1.
• Top
  • Description: Top vertical pixel offset in source image for what to include in display.
  • Min: 0.
  • Max: H - 1.
• Width
  • Description: Pixel width of source image to include in display.
  • Min: 1
  • Max: Left - W - 1.
• Height
  • Description: Pixel height of source image to include in display.
  • Min: 1
  • Max: Left - H - 1.

Circular Display Information

Assumes pixels are 0 indexed, W = pixel width of source image, H = pixel height of source image.

• Left
  • Description: Left hand side horizontal pixel offset in source image for what to use as center in display.
  • Min: 0.
    • Max: W - 1.
• Top
  • Description: Top vertical pixel offset in source image for what to use as center in display.
  • Min: 0.
  • Max: H - 1.
• Radius
  • Description: Pixel radius in source image to use in display.
  • Min: 1.
  • Max: No x,y satisfies ceil[(x + Left)^2 + (y + Top)^2] = Radius^2 and is not in [0,W-1]x[0,H-1].

Member

A membership is the representation of an actor relevant to channel ownership. All channels are owned by a member, and a single member can own multiple channels simultaneously. For more information about what information and actions are associated with a membership, please read

https://joystream.gitbook.io/joystream-handbook/subsystems/membership#membership

Channels

A channel is a venue for announcing content, under some theme, over time by the same publisher. Channels live on the blockchain itself. All content is published under channels, and each channel is owned by a single member. Currently, one can assume that a single member can have an unlimited number of channels.

Channel Status

The status of a channel has two parts. Firstly, it's whether it is public or not. Publicness is under the control of the channel owner, and it just signals to compliant user experiences whether any content, or the channel itself, should be presented to users. A typical use case for this is when the channel is in some intermediate maintenance state. Second, is whether it's curated or not. Curated status is under the control of platform curators, and it just signals the exact same semantics as being non-public, the only difference is that it is forced by the curators, as compared to being optionally signalled by the owner.

Channel Creation

Channel creation is a blockchain transaction, and it must be signed by the controller account of the membership of the would-be owner of the channel. Executing the transaction will require paying a nominal fee from the same account.

When creating a channel, the following must be provided:

• Owner: The member to whom this channel will belong.
• Title: A human readable title to be displayed in Atlas.
• Description: A longer free text human readable description to be displayed in Atlas, cannot have any formatting, just raw text. Atlas applies formatting.
• Cover: URL and rectangular display information for cover, if present.
• Avatar: URL and circular display information for channel avatar, if present.
• Language: The primary language, if any, of the channel. If a language is defined, it will be one among predefined set of languages.
• Publicness: Publicness of channel.

Channel Editing

Channel creation is a blockchain transaction, and it must be signed by the controller account of the membership of owner of the channel. Executing the transaction will require paying a nominal fee from the same account.

All fields provided in the creation phase, with the exception of the unchangeable owner, can be edited in a single transaction.

Videos

Videos have two parts, metadata which lives on the blockchain itself, and the video media, which lives in secondary storage infrastructure. The Joystream system has its own built in storage system to which publishers can publish video media, but they are also free to store the media on any third party infrastructure which is reachable via HTTP. Currently, a single channel can have an unlimited number of videos, and the storage infrastructure also allows a single member to store an unlimited number of media files, however each file must be on more than X MB.

Categories

There exists a finite, but dynamic, set of content categories on the platform. Each video is assigned to exactly one such category. Each category has a unique human readable name, and a longer description of the semantics of the category. Only platform level curators can manage the set of currently available categories.

Publish Video

Publishing a video has two steps. The first step is two publish the video media on some infrastructure, and the second step is to publish the video metadata to the blockchain.

Publish Video Media

Video media that lives on non-Joystream infrastructure, then it is simply assumed that it is reachable via some HTTP URL.

Video media that is supposed to live on Joystream infrastructure is published as follows. The process has two steps:

1. The first step is a blockchain transaction signed by the controlled account of the membership corresponding to the channel in question. This transaction includes a hash digest of the media to be uploaded, it causes the blockchain to automatically select a Joystream storage provider host which should receive the upload. This host will now accept an upload from the user, provided the file matches the hash digest in the original transaction.
2. The second step involves the en user actually attempting to upload the file to the designated storage provider.

This process will result in unique identifier, called a data object id, which can be used publishing of the video metadata to the blockchain.

Publish Video Metadata

Publishing video metadata is a blockchain transaction, and it must be signed by the controller account of the membership of owner of the channel. Executing the transaction will require paying a nominal fee from the same account.

When publishing video metadata, the following must be provided:

• Channel: Channel within which video lives.
• Category: Category to which this video corresponds.
• Title: Display title.
• Description: A free text description, must not have any high level encoding.
• Duration: The number of seconds the video lasts.
• Preview MAX: URL and rectangular display information for biggest preview - used when loading in playback, if present. The aspect ratio of the rectangular display information must match aspect ratio of video media.
• Preview MID: URL and rectangular display information for biggest preview - used when showing video as primary search result, if present. The aspect ratio of the rectangular display information must match aspect ratio of video media.
• Preview MIN: URL and rectangular display information for biggest preview - used when showing video in smallest minified view on channels/scrolls, if present. The aspect ratio of the rectangular display information must match aspect ratio of video media.
• Language: The primary language, if any, of the video. If a language is defined, it will be one among predefined set of languages.
• Media: Describes underlying media asset of video, consists of:
  • Pixel dimension.
  • Byte size.
  • Encoding: has to be one among a standardised set.
  • Location: is either an arbitrary HTTP URL, if it lives on third party infrastructure, otherwise it is the data object id.
• Marketing: Whether or not Video contains marketing.
• PublishedBefore: If set, some date and time in the past when the content was originally published, outside of the platform.
• Publicness: Publicness of video
• Explicit: Whether the Video contains explicit material.
• License: Is either one among a standardised set of Creative Commons licenses, or some user provided free text licenses.

Edit Video Metadata

Editing video metadata is a blockchain transaction, and it must be signed by the controller account of the membership of owner of the channel. Executing the transaction will require paying a nominal fee from the same account.

All fields provided in the creation phase, with the exception of the channel, can be edited in a single transaction.

Product Constraints

• The publishing experience is part of Atlas itself, it is not a standalone product.
• No inter session state that is not part of blockchain or storage system.
• Assume the user does not necessarily have any funds, a browser extension for holding funds.
• The overwhelming majority of Atlas usage sessions will be in the form of consumers viewing content, therefore, all the complexity of wallets, funds, channel creation an associated on boarding, must be hidden away from these sessions.
• There must be systematic handling of
  • loading states
  • empty states
  • error states
  • transitions.
• Onboarding is required.

Personas

Jun

Jun has just learned about Joystream from a friend, but does not himself know anything about the project, or about crypto currency. He is intrigued at the prospect of earning some spending money and to build an audience on a new platform, so he is interested in trying to publish some private recordings of himself playing online Poker while commenting on strategy, trends and wider social issues.

Jun User Stories

• As Jun I would like to learn what steps are involved from start to finish, to create a channel and publish my first video on Joystream.
• As Jun I would like to get help getting my wallet installed.
• As Jun I would like to get help acquiring my initial funds to create a membership and channel.
• As Jun I would like to create my first channel.
• As Jun I would like to publish my first video.

Angela

Angela is a very experienced content creator. She already has a very well known crypto currency related account on YouTube, but she also publishes to Joystream due to the unpredictable banning of crypto content on that platform, and the fear of loosing her channel there at any time.

Angela User Stories

• As Angela I would like to see all my memberships and associated channels.
• As Angela I would like to see all videos published to a given channel.
• As Angela I would like to update the metadata associated with a channel.
• As Angela I would like to update the metadata associated with a given video.
• As Angela I would like to publish a large number of videos at once.

The search view UX exploration

During the most recent UI review, we've discovered some discrepancies in assumptions about the search experience in Atlas. The design seems to think of the search as more of an overlay over whatever is displayed on the screen before starting the search, while the current implementation takes a more traditional approach (as seen on Youtube for example) of treating the search as a separate view. This creates differences in expectations - an overlay should be closeable, revealing whatever is behind it in the state it was left. However, a separate view doesn't have this property - it only lets you navigate back to the previous view you've visited, with no guarantee of preserving the state.

For Babylon release, we've decided to postpone any further decision and continue with whatever the current implementation provides. It would be wise to revisit this approach in the future and figure out what's the desired experience.

Introduce Featured video on channel page

Some version of a very prominent intro video on a channel page.

Gallery Error Handler disappears for a brief moment

Currently, a gallery error handler will go back into a loading state for a brief moment before going back to the correct state.

Add virtualization

Scope

Add virtualisation for

• Infinite grids
• List of notifications

Context

Currently, all items in Carousel component are displayed as they are, which can cause performance problems when a lot of items are to be displayed.

We should consider adding virtualization so elements that are offscreen don't need to be rendered, possibly something like https://github.com/bvaughn/react-window

Personalisation v2

Personalisation in Atlas: v2

Background

The current version of Atlas being built is an identical experience for all users in that it is not impacted by user state in any way. This is of course very limiting, and this issue attempts to describe a design that may allow us to make the first steps in the direction of personalisation. The design is still based on the base established here

https://www.figma.com/file/rBjfm2tJ2Pr9M0UNTduU9v/Joystream-Atlas?node-id=730%3A5283

Deployment

It is as of yet unclear how this will be deployed, but most likely this will not require altering the runtime in any way, but may require some new temporary Jsgenesis hosted infrastructure. This will have to be determined later.

Goal

1. Consumer-to-channel follower relationship is introduced.

2. Backlog of watched, but interrupted, videos is introduced.

3. UI improvements

Requirements

Client-Side Only User State

We will not have any server side hosting of user state, hence it will all live in local storage. This has the implication that clearing the browser history, or going to a private session, or going to a new browser, or a new device, all implies that prior user state will not be transferred over. It is not clear what long term approach to take. An implication of using local storage is also that there are no accounts and corresponding signup, login and logout flows.

Orion: Trusted & Trusting Follower and View Count Server

Adding Follower Count

Orion needs to be extended to not only hold content view counts, but also hold representations about follower relationships, so who followed what channel when.

All queries and mutations are through a GraphQL API still.

Event Data Model

Currently we have a state based data model for content view counts, so we only represent the cumulative view count for each content item. We now want to transition from state to event based model, so that we maintain much richer information that facilitates much richer queries and Sybil prevention.

Actor Identification and Authentication

The lack of any events has meant that we did not represent any form of actor in the data model, however, now it makes sense to introduce this in some way, but we can do something trivial like using the remote host. This is not stable in any meaningful way, but it may have value for simple debugging and analytics purposes for now. In the future we will probably add some incrementally more sophisticated identification and authentication scheme on top of this.

Hosting

There will still only be a single hosted Orion instance operated by Jsgenesis for this release.

Content Directory

We need help from Leszek on these points:

1. Introduce curator updatable information about the current hero section featured video.
2. Introduce a separate channel category type, similar to video categories, and associated each channel with such a category.
3. Introduce featured channels.

Query Node

We need help from Metin or Arsen on these points:

1. Needs to be updated to support channel categories.
2. Needs to be updated to support hero section featured video.
3. Needs to be updated to support featured channels.

CLI

We need help from Leszek on these points:

1. Needs to be updated to support channel categories.
2. Needs to be updated to support hero section featured video.
3. Needs to be updated to support featured channels.

Migration

None. Channel owners will need to bind their channel to a category, but no migration is required due to content directory schemas.

UX/UI

Home Screen

The home screen, also referred to as the "landing page" internally, has the followings structure, going section by section from top to bottom.

1. Featured Content: Same as today.
2. Continue Watching [carousel]: If the user has started, but not completed, watching at least one video, then the continued watching section should include this video in the carousel. If there is no such video, the section is omitted. No See All.
3. One of the following (No See All):

• From Channels I Follow [infinite scroll]: All videos available across all channels the user follows published no more than Y days ago, if at least some number X, otherwise skipped.
• Recent Videos [infinite scroll]: All videos available across all channels, listed in reverse chronological order.

Videos

Exactly the same as the current "Browse" screen for the Babylon release, except

• title is "Videos"
• a carousel, titled "Featured", between the title and the category selector, which contains a set of featured videos. These videos are not from a single category, which is part of the reason why this carousel lives above the category selector. We can play with allowing these videos to be larger than the videos in the infinite scrollers also. When scrolling, these videos are, like the page title, only visible when at the very top of the page, unlike the category selector.
• introduce an "All" meta category which is selected by default.
• videos are ordered by most recently created first.

Channels

Exactly the same as current "Browse" screen for the Babylon release, except

• title is "Channels"
• a carousel, equivalent to the featured videos carousel, except for channels.
• introduce an "All" meta category which is selected by default.
• channel are ordered by most recently created first.

Menu

Presentation

• UI for all states: #17
• UX
  • Remains stable during scrolling of the main page
  • Entirely hide when on playback mode, only allow opening when hamburger menu is clicked, but have flow over, like on the design

Structure

• Home
• Videos
• Channels
• In-lined list of channels you follow, as below:

Old Top Menu & Search bar

• Drop the icons, but don't introduce the <> buttons that were primary added for Electron variation
• center search bar, as in the original design.
• make search bar escapable, as in the original design, w.r.t this => #23
• show search history, as in the original design, using local state.
• up to date transitions for search bar entry, search and exit.

Miscellaneous

• #18
• #133
• #138

Milestones

Please suggest rough outline of who does what in what order.

Implement log collecting

As Atlas heads into the phase where it will be finally used outside of the development team, we should integrate some log collecting solution into it. This ensures that if users run into some bugs/errors we don't encounter ourselves, we know of their existence and hopefully can reproduce&fix them.

POC: Implement query node fallback

Context

Add a possibility for Atlas to try out different query nodes from a provided list once the request to the first one fails

Scope

• Add a "list" of QNs to Atlas to be used as fallback solution
• The list will be provided by the environment variables

Fix video playback loading layout jump

In the video playback view, once the video metadata (title, etc.) finished loading, the placeholder for the video player is hidden and the video player itself is displayed. For some reason, for a brief second, the player will have a very low height before going back up to its proper sizing. This causes the page layout to jump around a bit. We need to alleviate that some way. Introduced in Joystream/joystream#1643

Content Progress Issue

Purpose

This issue is for summarizing meetings on the content-seeding project for Atlas.

Atlas/Query node naming/types mismatch

During the initial integration of Atlas and the query node, some incompatibilities were found. This issue compiles the ones I've found so far. Please mind that it's possible there are some that I've missed and will be found only later once it's actually possible to test Atlas with the real query node.

Mismatch on the query name

Connection queries

Atlas uses a pluralized form of a noun with a Connection suffix, the query node uses a singular form of that same noun. E.g. Atlas - videosConnection, query node - videoConnection.

Recommendation: Update the query node to use the plural form.
This isn't clearly defined by the Relay connection spec (it constantly uses just the plural noun, without the suffix), but the GraphQL docs use the form used by Atlas (https://graphql.org/learn/pagination/#complete-connection-model)

Search queries

Query node uses several queries for searches. That includes titles - query to search channels and videos by their title. Atlas uses the same query but calls it search instead.

Recommendation: Provide a more descriptive query name on the query node side. titles suggests this query allows fetching titles, and that's not the case. I believe queries should be named based on what they return/what purpose they serve instead of what their input arguments are. I suggest just search or if we want to be more explicit - videosAndChannelsByTile or something similar.

Mismatch on the field name

List of mismatches with recommendation on which version to settle on:

• Video.publishedOnJoystreamAt (Atlas) <-> Video.createdAt (query node) - use query node version
• Video.thumbnailURL (Atlas) <-> Video.thumbnailUrl (query node) - use query node version
• Channel.coverPhotoURL (Atlas) <-> Channel.coverPhotoUrl (query node) - use query node version
• Channel.avatarPhotoURL (Atlas) <-> Channel.avatarPhotoUrl (query node) - use query node version
• Channel.handle (Atlas) <-> Channel.title (query node) - use Atlas version

Mismatch on the field type

• Channel.coverPhotoUrl, Channel.avatarPhotoUrl:
  In the schema used by Atlas, both of these are nullable and that was our assumption during implementation (e.g. provide default channel avatar/cover). The query node marks both of those as non-nullable.
  Recommendation: Make it consistent with the constraints of the content directory - if the fields aren't required, make them nullable

• Video.channel:
  Atlas assumes the channel will never be null for a video, i.e. every video is always published by some channel. The query node allows the channel to be nullable - that would have a lot of UI implications in Atlas.
  Recommendation: Make the channel field non-nullable

• Video.category - Nullable in the query node, required in Atlas.
  Recommendation: Changing this doesn't have any implication for Atlas at this point, so I think it's mostly a product question @bedeho

• Video.publishedBeforeJoystream - String in Atlas, Int in the query node.
  Recommendation: Use the DateTime (same as the createdAt) for consistency. Also possibly we should rename the field to publishedBeforeJoystreamAt so it's clear it contains a timestamp and is not a boolean flag for example.

There's also a couple of nullable fields in the query node that in my understanding should definitely be non-nullable and rather are this way because of some error:

• Video.media
• Video.license
• VideoMedia.location
• VideoMedia.encoding

Mismatch on type assumptions

• MediaLocation
  Atlas assumes this type to be a simple union - JoystreamVideoMediaLocation | HTTPVideoMediaLocation - it has to be one of these. However, the query node has a separate MediaLocation type with fields httpMediaLocation and joystreamMediaLocation. In general, this structure is fine, but in the query node, both of those fields are nullable. This means that the API gives no guarantee that at least one of these values will be present. This poses a challenge to a client as it can theoretically get no location at all.
  Recommendation: Use some kind of union that will guarantee a value is present at all times

• License
  Basically the same situation as above, but with KnownLicense and UserDefinedLicense.
  Recommendation: Same as above, but with a lower priority

Figure out the empty search results view

Currently, the design provides a screen to be displayed when there are no search results for a specified phrase. However, the search view contains the tabs to filter the results - "All result", "Channels" and "Videos". It's possible for the search result to contain only channels or only videos, making one of the tabs empty. We should figure out what should be displayed in that case - should one of the tabs get hidden, etc.

Add some visual clue a new search has been fired

Right now if a users fires up a search and then changes the search string while the search results are loading, there are no changes in the UI.
We should add a way to notify a user that a new query has been submitted and that the screen is not "frozen"

Atlas style guide

At a later stage of development, it'd be nice to have some kind of style guide where we can put some common decisions regarding styling the codebase

Rework VideoPreview loading transition

Right now, animations for a preview fade in fire each time the component is mounted on the page. Improve this by making the animation fire only when a component is mounted for the first time (the first time data is fetched).

See Joystream/joystream#1480 (comment)

Design Input for Atlas in Babylon Release

Background

This issue is meant to be the place to accumulate descriptions of problems where the solution has been decided by the Atlas team to require input from a designer for the Babylon release. For each issue identified, add a new reply to this issue. Then we can compile this into one coherent desing brief which can be fired off to the designers promptly.

Carousel problems when video preview is hovered

The Carousel Arrows are aligned to the middle of a video preview cover, but when hovering a video preview, the cover raises up by ~8px and the button looks misaligned.
See here:

Client side browser based transcoding

Things like changing the bitrate (transrating) or size (transsizing) of the media, or do additional things like add watermarks could be useful, and diong it server side could get too complex for the near terms, using a client side solution could be worth investigating.

https://ffmpegwasm.github.io/

Glider has inconsistent spacing

Right now, our integration with Glider has inconsistent spacing, to be more precise, it does not take into account the margin of child elements, making it hard to do things like aligning arrows to the edges of the Carousel children (see issue Joystream/joystream#1708 part 2). It also looks like the way glider is sizing children its slightly different from what CSS grid does, this effect has been observed (see Joystream/joystream#1649 ) but it might be caused by the same issue described above.

Improve the Carousel to work exactly like the Grid component does in terms of spacing and maybe introduce a gap to space the children elements in a way that is consistent with Glider internal workings.

If this is not possible, we might want to consider rewriting a Carousel implementation from scratch that supports this.

Atlas product release plan preparation

Scope for the pre-release plan meeting:

• Identify outstanding problems existing in the app
• Figure out the details of work on responsiveness
• Figure out options for testing Atlas
• (nice to have) Explore options on hosting mock images/videos on Jsgenesis infrastructure

Create design for failed video playback

Currently we have a design for an error-wide view - what happens when the full view fails to load. We use that in the video playback view when we fail to fetch the video metadata. However, there's also another case we have to handle - what happens when the video media file fails to load for some reason. A design should be created that handles this case

Atlas Problems Tracking

This issue is meant to be the central source to gather all problems and observation coming up while building Atlas.

I suggest we keep each comment / problem in its own comment to keep this issue more organised.

Channel view cover improvements

• Decrease the displayed cover height, make the content overlap bigger
• Align the name + avatar with a fixed gap w.r.t. the first content row

How To Change Mocked Images in Atlas

Here is a short guide to change mocked images in Atlas, depending on what images are changed, the steps are slightly different, but the procedure is overall the same.

Get Started

Regardless of which image you would like to change, to start you need to:

1. Clone the Joystream monorepo and checkout to the init_atlas branch.

$ git clone [email protected]:Joystream/joystream.git
$ git checkout init_atlas

2. Install dependencies and start the app.

$ yarn 
$ yarn start 

3. Copy the image to joystream/atlas/packages/app/src/mocking/data/images, if the folder doesn't exist, create it.

Now the next step is slightly different depending which image you want to change.

Change a Channel Avatar.

4. Open joystream/atlas/packages/app/src/mocking/data/mockImages.ts in a text editor and add the following at the top of the file:

import MyImage from './images/my-image-name.jpg' 

//... potentially other code

export const channelSources = [
  'https://source.unsplash.com/collection/781477/320x320',
   //... other URLs or Images, you can change the order in which they're displayed here
   MyImage,
]

Change a Video Poster

4. Open joystream/atlas/packages/app/src/mocking/data/mockImages.ts in a text editor and add the following at the top of the file:

import MyImage from './images/my-image-name.jpg' 

//... potentially other code

export const posterSources = [
  'https://source.unsplash.com/collection/781477/320x320',
   //... other URLs or Images, you can change the order in which they're displayed here
   MyImage,
]

Change the Hero Background Image

4. Open joystream/atlas/packages/app/src/views/HomeView.tsx in a text editor and add the following at the top of the file:

//... Lots of other imports here
import MyImage from '../mocking/data/images/my-image-name.jpg' 

const backgroundImage = MyImage

//... other code

Adding multiple images

To add multiple images, just follow the procedure multiple times. Remember that each image in posterSources or channelSources should separated by a comma.

For any issue, feel free to tag me in a comment here or reach me on Rocket Chat.

Atlas UI Review

• Loading should not result in layouts jumps.

• The top cover image/video should have its top left corner fixed in the top left corner of its scrollable container, and the height of the image/video should have some fixed proportionality to the viewport width. This should (I think) result in pushing content below up and down as scaling is being done, that is totally fine. The way it currently resized ends up drifting in a way which would not work if there was video playback.

• The resizing policy of videos in a flowing admits to these constraints

  1. Image and image container aspect ratios must remain fixed and identical.
  2. The margin between videos must remain fixed.
  3. The margin between the most horizontally peripheral videos and the view port must remain fixed.
  4. Adjust the text size to move in concert with overall image size. Perfect proportionality could be tried, but if that creates problems, some sort of step-wise relationship could also be tried.
  5. There must be two fixed, but easily configurable, lists of integers 0 < v_1 < ... < v_n and N_0, ... , N_{n+1} > 0. Let I_0 = [0, v_1), I_1=[v_1, v_2), ... , I_{n+1} = [v_n, inf). Now if the viewport width is in interval I_i, then the number of videos per row is N_i.
  6. Text is clipped from expanding beyond two lines (currently I see cases where it goes to three, which shifts rows)

• Video carousels must be subject to the same resizing policy as above, also including carousel headline test in the sizing policy, otherwise you get this sort of clipping:
  

• Channel carousels must be subject to the same resizing policy, also including carousel headline test in the sizing policy, otherwise you get this sort of clipping
  

• Channel name must not exceed implicit margin w.r.t. grey box induced by avatar radius
  

• Loading uses opacity rather than genuinely changing the base color to darker, however this results in artifacts when the background has some visual feature, e.g. such as another loading container. The only example I see so far is for channel loading, and its not that bad but it would be good to fix if its easy to fix. If its not easy to fix, then it should be made an issue out of for later.
  

• Channel titles should not be wrapped, but instead clipped with Ellipsis, however more horizontal space than now could be justifiable.
  

• Channel cover should follow same resizing rule as landing page cover, right now the top drifts up and down.

• I assume that the current "Loading" and "Loading Channel ..." will be replaced by the loading screens.

• The top menu should be fixed to look like this when neutral. Later we will reintroduce the left hand side menu, but this was the best compromise the designer could come up with right now.

• Channel avatar must always be a perfect circle, regardless of source image dimensions.

• Joystream/joystream#1583

• Joystream/joystream#1582

• Depending on how time intensive it is, we should have the player controls be aligned with video player width, as on youtube (try going into full screen or cinema mode on youtube to see the effect). When we go to full screen mode in Atlas, this works properly, but not in normal mode.

• Remove channel avatar for previews of videos on the same channel, this also applies to previews of other videos from the same channel from the playback screen. Remember to make loader without avatar also.

• Drop the "Videos" title on the channel view.

Use Typography component for all the text

To ensure our text styles are kept consistent across the app, we should leverage the Typography component more. This way we wouldn't need to provide manual font-{family,weight,size} but only a predefined variant. We should also integrate loading state into that component so it's easy to create placeholders for headers.

Rename component to Text

Determine how to integrate with website

Switch to a CSS Variables based theme

Currently our styling process is based on theme values set in some static files. This has been working fine for now, but I would like to discuss what might be an improved and more maintainable system.
I propose we move our theme to use CSS variables, I hope that discussing and evaluating this proposal can help us improve our current theme regardless of if we end up adopting it.

What are CSS Variables? And how can they be useful to us?

From MDN:

Custom properties (sometimes referred to as CSS variables or cascading variables) are entities defined by CSS authors that contain specific values to be reused throughout a document.

In practical terms, if now we style a Button like this:

// colors.ts
{
// ... other theme values
blue: {
    500:  "#4038FF"

// Button.tsx
import {colors} from "path/to/theme"

const Button = styled.button`
    background-color: ${colors.blue[500]};
`

With CSS Variables we would instead do this:

/*  inside theme.css */
html {
  --color-blue-500: #4038FF;
/* other theme values */
}

// Button.tsx
const Button = styled.button`
  background-color: var(--color-blue-500);
`

CSS Variables have several small benefits, which I'm not going to go into since I don't think are relevant for us:

• They are animatable, so it becomes possible to animate things like background gradients.
• They are pure CSS and supported on every major browser, framework agnostic etc...
• They don't cause re-renders when changed (for example for switching from dark mode to light mode or to prevent some performance impacting re-render)

The main benefit I see for us, which makes the idea worth exploring is the possibility of defining how things should change relative to screen size in one single point of the codebase. Let me give an example:

Suppose we want the text of whole app to shrink or grow based on screen size, and we want every component to have this behaviour.
How would we do that now?
As far as I can see, with our current system we would have 2 options for achieving this:
a. Look up each component that defines a font-size, add media queries or a fluidRange to each component to scale it accordingly.
b. Add media queries to the top level component, change theme values based on the results and switch up the theme in the theme provider for that.

Option a is a nightmare to implement in terms of development experience, one might argue that if we wrap all the app text into a Text component than we have just one component to change, while true, I believe this is hard to enforce and a bad DX as well.
For example you would have to do:

<Button><Text>Click</Text></Button>

instead of

<Button>Click</Button>

Option b is more easy to implement but requires swapping out the theme, which would make every styled component re-render.

With CSS Variables, it would look like this:

/* theme.css */
html {
/* just one example of fluid typography */
  --fontSize-normal: clamp(1rem, 2.5vw, 2rem);
}

// Button.tsx
const Button = styled.button`
font-size: var(--fontSize-normal);
`

I find the CSS var option to be superior by far to both options in terms on maintainability.
One aspect that would be fun to explore is if this also helps keep animations in sync, since CSS variables are animatable, it might be possible for example to add a fade animation to all text at once, without having to change components.

Downsides and possible workarounds

For now, I only came up with two possible downsides to this approach.

1. We lose type safety on theme values.
2. CSS Variables are global state, so they have all the downsides of global state. For example if two different components were to change the same CSS variable, weird bugs could take place.

Regarding 1, a quick workaround would be to define the theme values in a static file and use that to initialise CSS Variables, then take use this file to define a typed getter function for CSS variables, going a bit more into details:

// GlobalStyles.tsx
import theme from "path/to/theme"

const globalStyles = css`
   html {
    --colors-blue-500: ${theme.colors.blue[500]};
   // ... other theme properties
}
`

// cvar.ts
import theme from "path/to/theme"
// could be an object too instead of a function
function cvar(key: themeKey){
  // have a map that associates each theme key to the corresponding CSS Variable name, for example colors.blue[500] maps to var(--colors-blue-500)
}

Then to use it in a component

import cvar from "path/to/cvar"
// Button.tsx
const button = styled.button`
// you get autocomplete here
  color: ${cvar('colorsBlue500')}

And type safety is restored.

For point 2. I don't think there is a workaround, but I can't think of a single use case where we would change a global CSS variable at runtime in multiple components.
And if we needed to do so, we could redefine the variable in the components that need it to prevent global conflicts.

Feedback

I'm sure there are some downsides I might have overlooked or ways to improve this proposal, so any feedback is welcome :)

Orion integration improvements

Currently, the Orion integration is done the simple way:

• the video views are queried synchronously, so only after the query node request finishes
• view are queried on one by one basis - even though we fetch the list of videos from the query node and Orion allows batched lookup, we do that separately for every video

Going forward, we should:

• do the query node and Orion queries in parallel to reduce the request time
• use the batched lookup to reduce the number of requests to Orion

Atlas v1 Progress Issue

Purpose

I am starting this issue to summarize our conclusions and focus from weekly Atlas team meetings. We add a new entry here as we make progress. We will probably switch to a different management mode when Atlas is incoroprated into a full network release.

Switch icons on mute button on landing page.

Currently it has the reverse semantics compared to other major video platforms.

Make channel and video views use paginated queries

Currently, both video playback view (more videos section) and channel view use a regular video grid for displaying the channel's videos. Furthermore, they don't use paginated queries but rather just request all videos from a specified channel via the channel's videos field. This works for now, but once channels start having more videos, pagination will be a must.

As part of this task, support for passing channel ID to the InfiniteVideoGrid should be added and that component should be used for the aforementioned views (unless we don't want infinite grids there, then we only need to use paginated queries)

Atlas playlist & series components

WIP.

test

Progress indicator in carousel

Currently, there is no visual feedback to the user how many times they will have to click before they have exhausted the carousel, they will just notice content repeating at some unpredictable time. This is lack of predictability discouraged exploration.

VideoThumbnail field should be Nullable

The videoThumbnail field should be allowed to be null.

This requires coordination from the Hydra and Atlas teams and some minor designer work:
It is necessary to:

• Change the query node to make the videoThumbnail nullable
• Change Atlas to handle a null videoThumbnail gracefully
• Design a fallback cover for when videoThumbnail is null

Spice up the README

Why don't we add a pretty App preview shot to spice up the README, will evoke interest for newcomers.

Elevate Atlas to a separate repository

As Atlas keeps growing we decided it's gonna be best to elevate Atlas to a separate repository. Some reasons behind it:

• better access control - right now Bedeho is required to merge any work, which is becoming cumbersome to both the development team and him; with a standalone repo we can have the write access within a development team
• no real external Joystream dependencies - Atlas doesn't rely on any code outside of its own - at the moment it lives entirely on a separate branch

Some things to keep in mind when processing with the transition:

• what's the access control? who does have write access?
• devops - how do we ensure our current pipelines keep working? maybe it's a good time to explore github actions based deployment?
• commit history - ideally we'd keep the entire commit history in the new repo. what's the best approach to that? is it possible to extract just the commits related to the atlas directory?
• issues - we'll probably have to move Atlas issues out of the monorepo. what's the best way to do that?

Tabs on channel have visiblity problems

Even when a perfect cover is chosen, which is largely black, the tab text is actually quite small and thin - making it hard to perceive effortlessly.

The most severe problem is when the background is not ideally picked, then it looks quite bad.

Introduce new menu design

A new design with state variations for selection, hovering and press, both for collapsed and expanded mode.

https://www.figma.com/file/rBjfm2tJ2Pr9M0UNTduU9v/Joystream-Atlas?node-id=2159%3A0

Update @graphql-tools library

We currently have some workarounds in Orion integration code that were needed until some fixes were released in @graphql-tools library. Let's update the library and remove the workaround in Atlas

Upgrade React, CRA and Typescript

We should update to the newest versions of the tools we use so we can use the latest features and don't build up the technical debt. Most notably, the newest release of CRA includes some improvements which can vastly improve the developer experience

Introduce missing Atlas interaction transitions

Here is a menu showing the different missing interaction transitions

https://www.figma.com/proto/2Q0wavkniGCAlnmvQPzXRf/Joystream-Atlas---Duplicate?node-id=2115%3A23&viewport=1311%2C1101%2C0.1049661710858345&scaling=scale-down

We are not doing every example on the screen, some are just demos or explorations:

• Search Results (see top loader bar): The Recent Searches should be added because we are adding personalization as a major next step.
• Jump to video v2.
• Page Transition
• Channel Preview (see top loader bar)
• Discovery v3

Query node integration

Enable Atlas integration with a real deployed query node:

• provide a way to switch between mocked/real API
• test that everything works as expected

Video completion redesign

When a video is completed, we currently just allow the user to click "next" to go to some new video,

however a richer experience could be useful offering

• publisher defined actions or buttons inside the video display for doing some contextual action (link, follow, jump to new video, share, etc.)
• a cover photo could be useful
• a countdown indicator that takes you to some new video or content: its not whether this should be under publisher control, or whether the client should try to figure it out. In any case, an image preview of that next item should be shown, not just the title.

Move to react-router@6

Will be ready by end of year hopefully.

Avoid onClick navigation in favour of anchor elements

Currently in a few places we do programatic navigation on onClick (e.g. video preview cover and channel, channel preview). It would be a better practice to use anchor tags for that.

Implement cross-browser video auto play [Atlas]

In general, because of browser inconsistencies (and browser design), it's non-trivial to implement cross-browser autoplay of video. That's something we will need for Atlas though. If a user visits the video by its link, the playback should start automatically