KLIKsee

Software Requirements Specification

Nicola De Franceschi, CTO

Introduction .........................................................................................2
Definitions ...................................................................................................3

Overall description ..............................................................................3

Application ..................................................................................................3
Website ........................................................................................................4
Users ............................................................................................................4

Specific requirements - Application ....................................................5

User interface ..............................................................................................5
Server communication .................................................................................8
Movie recognition ........................................................................................8
Media player communication ......................................................................9
Windows versions compatibility ...............................................................10

Specific requirements - Website ........................................................11

Website content .........................................................................................11
Login ..........................................................................................................12
Social networks ..........................................................................................12

Specific requirements - Server and database .....................................13

Server architecture .....................................................................................13
Database design .........................................................................................14
Server API .................................................................................................15
Performance requirements ........................................................................16

Use Cases - Application .....................................................................16

Appendix ...........................................................................................17
Sidebar contents list policy ........................................................................17

Introduction
This document contains the specifics of the web services to be developed for KLIKsee.
This document contains the specification of all the software that KLIKsee will consists of. In
this way it will be easier to understand how KLIKsee will work and the interactions between
its parts.
However, the implementations required from the supplier is limited to the following:

Implementation of the databases as described later.

The website layouts for the different web pages will be provided by an external web
agency as static HTML-CSS pages with placeholders for images and texts. It is required
to replace them with dynamic content retrieved by the database.

The implementation of the web API needed for the client application (developed by an
external company), as expressed in high level of abstraction here and to be designed
together by 1) web services supplier, 2) client application supplier and 3) the KLIKsee
CTO.

Deployment on a test environment (for internal test usage) and the production
environment.

Testing

Its is required to have access to the implemented code during all phases of development by
the KLIKsee CTO. This will allow early detection of misunderstanding.

KLIKSEE SOFTWARE REQUIREMENTS SPECIFICATION

"2

Definitions
Term

Definition

KLIKsee application

The client software the runs in the users computer, interacts with the media
players the user installs and uses, and displays the graphical interface during the
movie playback.

KLIKsee website

The website on which the user can login, see her private/public pages, her
settings, explore movies and contents, etc.

Application user

User that downloaded and uses the KLIKsee application on her computer

Website user

User that registered on the KLIKsee website

Website guests

User that visits the KLIKsee website, but didnt yet registered to KLIKsee

Movie database

Database that contains all the informations about the movies and the contents in
them

Movie analyst

Member of the KLIKsee team whose job is the retrieve informations about the
content seen in movies and enter them in the Movie database

Media player or
Movie provider

Application on the users computer that she uses to watch movies (e.g. iTunes,
Windows media player, VLC, ), by downloading or streaming them. It
includes also websites (e.g. Netflix)

Movie content

Products, locations, cultural informations related to the each movie scene.

Movie version

Multiple version of the same movie can exists due to different movie providers.
Differences can introduces offset between two movie versions

Reference movie

For each movie, the version that was used to add content by KLIKsee analysts,
and that is taken as a reference from which the others versions time should be
synched to

Overall description
Application
The KLIKsee application will run on the users computer and will allow her to explore the
contents she sees in movies while watching them.
It will run in the background without interaction with the user for most of the time, listening
for notifications provided by the different media players. When the user starts playing a movie
in full screen, the KLIKsee application will provide access to the contents displayed on screen
for any given time. The users will then have the ability to like the content, mark them as
favourite, open its websites or buy it.
The user can at any time pause the movie and open a contents window, that displays all the
content that is in the movie currently playing.
The user will have the ability to login in or sign up to KLIKsee.

KLIKSEE SOFTWARE REQUIREMENTS SPECIFICATION

"3

Website
The KLIKsee website will contains all the informations about the contents of movies and the
user experience on KLIKsee.
The functions provided are listed here:

Function

Description

Favorites contents

The users can see the contents she mark as favorite during the movie and add or
remove favorite contents while exploring the KLIKsee website

Shared content

The user will be able to share the content on social networks

Movies watched

The user can see a list of the movies she watched

Top movies

The user will see the list of top movies integrated with the KLIKsee experience,
based on movies seen by other KLIKsee users

Movie suggestions

The user can be suggested about movies to watch based on the movies watched

Top contents

The user will see the top contents based on content other KLIKsee users
marked as favorite

Friends activity

The user can explore the activity on KLIKsee that her friends make public
available to others, such as favorite contents, shared content, movies watched

Account information

The user will be able to see her account information, and link accounts on other
social networks in order to have more functionalities such as sharing and friends
connections

Content information

Each content will have different information associated with it, such as website
link (or links), buy link (or links), a brief description, related and similar contents,
movies this content is in

Users
User

Description

Guest user

User that didnt sign up on KLIKsee yet, and hence it doesnt have access to all
the features of KLIKsee

KLIKsee user

User that singed up on KLIKsee and has access to all the features of KLIKsee

Analyst user

Member of KLIKsee authorised to add movies and contents

KLIKSEE SOFTWARE REQUIREMENTS SPECIFICATION

"4

Specific requirements - Application

User interface

"

"

KLIKSEE SOFTWARE REQUIREMENTS SPECIFICATION

"5

The application will have two main interface components, a sidebar and a contents window
(see images above).
During normal playback of a movie in fullscreen mode, only a small KLIKsee logo will be
present in the top right corner of the screen. The sidebar will appear when the user wants to
have access to it. It can do that by either clicking on the logo, or move the mouse pointer on
the left side.
The sidebar will show an header, the contents list, and a footer. The header will contains the
KLIKsee logo, the footer will show a button that opens the content window, and the content
list shows the contents of the movies in chronological order, with the last seen content on the
top of the list. Content that didnt yet appeared on screen will not be present in the list, and
the list will updated every time new content will be shown.
For each content, are provided four icon buttons that allows the user to mark the item as
favourite, open the related website, go to a e-commerce website to buy or share, respectively.
Full details about the sidebar content policy is detailed in the appendix.
Clicking on a content will open a small window that contains informations about the item,
such as pictures, description, link for the website, link for buying, share button. This window
will be semitransparent like the sidebar and the contents window, and will have an interface
like in the following figure.

Content info

Title
Lorem ipsum dolor sit amet, consectetur adipisci
elit, sed eiusmod tempor incidunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquid ex
ea commodi consequat. Quis aute iure
reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur. Excepteur sint obcaecat
cupiditat non proident, sunt in culpa qui officia
deserunt mollit anim id est laborum.

"
On the sidebar footer there will be a button used by the user whenever she finds a content
that is not been tagged by KLIKsee analysts and she wants to add that information herself.
She will then click the add tag button, that will open a dialog window where she can insert
the name of the content and optionally a brief description and send that to our analysts for
review, together with the movie info and the time position in the movie at which the content
appears.

KLIKSEE SOFTWARE REQUIREMENTS SPECIFICATION

"6

The contents window contains a header and the contents grid. The header contains the
KLIKsee logo, content filter options, search field and link to the KLIKsee website.
The content window will be open automatically when the movie finishes, or when the user
click the contents window button on the sidebar. When opening, the interface will take place
on top of the movies, fullscreen. If the movie is playing, it will pause the movie and start
playing back when the user exits the window.
The contents grid contains all the contents in the movie, in chronological order, with the first
seen content on the top.
Passing the mouse on top of each content will show the content name and the four buttons as
in the sidebar.
All the links will open on an external browser.
The user will have the ability (from both the sidebar and the contents window) to open the
application settings. The window will be divided in multiple tabs: one will allow the user to
see, add and modify the social networks account linked with her KLIKsee account; the
second tab will show the tag requests done by the user, and their status (approved or not, with
explanations); the third tab will include general settings; the last will provide the ability to log
out from the application.
The first time the user open the application, she will see a welcome window that let her log in
or sign up to KLIKsee. After logging in, and when the user opens the application by clicking
on the KLIKsee icon, a window should open that let the user see featured movie she could
watch, and her previous activity on KLIKsee. The user will have the ability to open the
KLIKsee website to interact more.

KLIKSEE SOFTWARE REQUIREMENTS SPECIFICATION

"7

KLIKsee

Featured movies

Last favourited content

Open KLIKsee website

"

Server communication
The application will need to communicate with the server in order to get information about
the movies and related contents, and save information about the user interactions with
KLIKsee application.
Movie and contents informations contains a list of all the contents in the movie with the
temporal position of them in the movie and their informations as provided by the database.
User interactions include logs information for statistical proposes (such as when the user open
the sidebar, how many times she open the content window, when she opens a link and which
one, which movies she watch and when, etc.) and when the user mark a content as favourite
or share it.

Movie recognition
The recognition of the movie the user is watching is done using different approaches. The
informations needed to be recognise of a movie are its ID inside our database and its
synchronisation offset with the reference movie.
Due to the multitude of movies versions available to the user (they may differ for different
movie providers, DVD/Blue Rays and/or between different files downloaded with torrents or
obtained by other means), its very important to establish a synchronisation mechanism
KLIKSEE SOFTWARE REQUIREMENTS SPECIFICATION

"8

between the movie the user is playing and the movie KLIKsee analysts used to add contents.
The KLIKsee application require only to know the offset between the two versions, from
which it can just apply this information in order to know when a content is actually showed
on the users screen. In particular, this offset could change during the movie (for example due
to the presence or absence of a scene). For this reasons the offset could be represented by
start_time-offset pairs, where start_time is the time when offset become valid; it will remain valid
until the next start_time.
The movie recognition logic will be provided and can then be considered as a black box for
the application developing proposes. The following is a UML class that describe the
recognition logic. The MovieRecognition singleton instance method recognise should be called
with the movie object to recognise. It will then be responsible to delegate the work to the
recognisers instances in order to obtain the required informations.

singleton class
MovieRecognition
movieRecognisers
recogise:(Movie)

"

Title
Recogniser

interface
MovieRecogniser
recogise:(Movie)

Hash
Recogniser

Audio
Fingerprint
Recogniser

Subtitles
Recogniser

Media player communication

For each media player, some informations must be obtained. In particular:

Info

Description

hasMovie

boolean, whether or not the player has a movie selected, that is either paused or
playing

isPlaying

boolean, valid if the player hasMovie=true, indicates whether the movie is playing
or its paused

isFullScreen

boolean, whether the player is fullscreen or not

currentMovie

object identifying the movie that is currently playing

currentTime

seconds from the beginning of the movie

synchedTime

seconds from the beginning of the movie, synched related to the reference movie

KLIKSEE SOFTWARE REQUIREMENTS SPECIFICATION

"9

The following describe the states and transitions between them for every media player the
user has installed on its computer.
Playing

Idle

Playing
Fullscreen

"
The KLIKsee application can interact with the players buy sending play and pause
commands and ask for informations about the movie currently played and the current time
position.
The KLIKsee application must take this informations for all the media player the users could
use, and choose from them the one that is currently playing a movie. In order to do this a
media player manager entity must control every one of them and identify the one that the
user is currently using. The following is a UML Class diagram that describe this logic. The
MediaPlayerManager and the implementations of the MediaPlayer interface will be provided by
us and can be considered as a black box from the developers point of view. Other classes that
implements the MediaPlayersManagerListener interface may register themselves to receive
notification of state changes of the media player.

singleton class
MediaPlayersManager
players
currentPlayer
play
pause
moveTo:(seconds)

interface
MediaPlayer
hasMovie
isPlaying
isFullScreen
* currentMovie
currentTime
synchedTime
play
pause
moveTo:(seconds)

"

interface
MediaPlayersManagerListener
onMediaPlayerManagerStateChanged

iTunes

VLC

Netflix

Movie

Windows versions compatibility

The application has to be compatible with the following versions of Windows: Windows XP,
Windows 7, Windows 8.

KLIKSEE SOFTWARE REQUIREMENTS SPECIFICATION

"10

Specific requirements - Website

The KLIKsee website will be designed by an external web agency, that will study and provide
the best layouts of the pages that composes it. Social sharing is at the core of time spent
online, and the KLIKsee website will provide social functionalities to the users, integrated
with existing social networks like Facebook, Twitter and Instagram. It will allow users to keep
track of the movies they watch via KLIKsee, items they saved and purchased as well as
discovering additional products and information by interacting with their friends, other
KLIKsee users around the world, creating a community of people that dont just watch
movies, they live them.
The KLIKsee pages will be delivered by the external agency as static mockup HTML-CSSJavascript. KLIKsee developers will be responsible to make the content dynamic by obtaining
the content from either the REST API or directly by querying the database.

Website content
The website will have the following static pages that describe KLIKsee:
General product information about the KLIKsee software,
Links to download the application,
The KLIKsee movie library.
The user will also have the ability to login or signup. When authenticated, other pages will be
available with dynamic content based on the logged user:
Home,
My Profile,
Friends,
Explore,
Account and settings.
The Home page will be an aggregator of the activity of the users friends, users will be able
to see what is trending on KLIKsee, such as popular movie titles, actors, newest content and
newest movies, most favourite content, most shared content, most purchased content.
The My Profile page will be a Pinterest-like wall where users will be able to post whatever
they have explored with the KLIKsee software. This page will be publicly accessible,
regardless if one is a KLIKsee user or not, based on the user privacy settings. The My
Profile page will also contain a brief BIO and a users top actions, the users KLIKsee
history, all the contents explored and movies watched, the sharing activity and a personal
favourited and bought items. In this page KLIKsee will provide suggestions and matches of
other movies to watch and similar contents to be discovered, purchased and shared.

KLIKSEE SOFTWARE REQUIREMENTS SPECIFICATION

"11

The Friends page will be populated with a users friends (KLIKsee users followed, Facebook
friends, Twitter, etc.). The user will also be able to sort and find other users (friends or not)
based on their movie history, to see what contents they liked and shared or purchased for each
movie.
The Explore page will be a library of all the KLIKsee movies/contents database. It will be
populated by all analyst generated content, user approved tagged content, the movie library,
and will be completely searchable by category, keywords, movie titles and genres. KLIKsee
will provide suggestions and similar items to explore related to the contents in a users library.
There will be a page of the website for every content, with images of it, a brief description,
links to the website and the shopping site, ability to add the item to the favourites, similar
products, movies the item is on, comments, friends who marked it as favourite.
Every movie will also have a details page with some info such as actors, top content in the
movie and similar movies.

Login
The users will be able to log in using either social networks accounts or by email-password
authentication.

Social networks
The KLIKsee experience will be improved by linking the user with her Twitter, Google+,
and Facebook accounts. She will have the ability to change this informations in the settings
page.

KLIKSEE SOFTWARE REQUIREMENTS SPECIFICATION

"12

Specific requirements - Server and database

Server architecture
Amazon S3
Static file and
resources
(photos, javascript,
static HTML, CSS, )

PostgreSQL
+ Replicas

Auto Scaling

MongoDB
+ Replicas

CDN
Amazon
CloudFront

Elastic
Load
Balancing
or
NGINX

EC2 Instance Contents

Web server +
REST server

Redis

(Spring MVC)

"

Amazon
Route 53
DNS Service

The server architecture will be composed, as in the figure before, by the following elements:
CDN: Requests are automatically routed to the nearest edge location.
S3 stores static content and resources.
HTTP requests first handled by ELB which distributes traffic among multiple EC2
Instances. EC2 instances are scaled by Auto Scaling to automatically adjust capacity up or
down. As an alternative, NGINX can be used as proxy to allow load balancing.
Web servers respond to users request using Spring MVC, REST is used for API (used from
KLIKsee applications)
PostgreSQL for database, plus replicas eventually in the future, with requests cached by
Redis (or memcached). MySQL could be used as well. The database should be configured
with at least one master and one slave instance. For the movies related contents, non
relational database (such as MongoDB) will be used, so that no schema is needed to
represent different content types (product, culture, actors, music, etc.) that hence need
different proprieties
Website content dynamically generated from web server for the main content of a page.
The content can be sent to the web browser using a technique similar to Facebook BigPipe
(https://www.facebook.com/notes/facebook-engineering/bigpipe-pipelining-web-pages-

KLIKSEE SOFTWARE REQUIREMENTS SPECIFICATION

"13

for-high-performance/389414033919). Alternatively, extra content (e.g. similar products,

comments,) can be requested after page load with AJAX. This will allow faster load of
pages with lots of dynamic content.
The web design will be provided (HTML, javascript and CSS)
The server architecture should use preferably Amazon Web Services, or similar services from
other providers.
All communications must be encrypted with SSL.

Database design
The following is a Database ER model of the data as the specifics in this document.

MongoDB

Content

Movie

{
_id : int,
title: string,
contents:[{
start_time: int,
end_time: int,
content: <Content>
}]

_id : int,
name: string,
description: string,
categories: [string],
links: [string],
buy_links: [string],
images: [string],
keywords: [string]

SQL database

User
Friend
id_user1
id_user2

id
1 name
email
[social networks
related fields]
1

*
1
1

*
1

*
action can be:
start_watching_movie,
end_watching_movie,
open_sidebar,
open_contents_window,
open_content_window,
open_link,
open_buy_link

Favourite
id_user
id_content
date

UserActionLog
id
id_user
date
action
id_content
id_movie
operating_system
media_player

Share
id
id_user
id_content
id_movie
date
[social networks
related fields]

*
ContentTag
id
id_user
id_movie
movie_time
date
content_name
content_description
receive_notification
approval_response
approved_content_id

"

KLIKSEE SOFTWARE REQUIREMENTS SPECIFICATION

"14

Server API
Movies
GET /movie/:mid
POST /movie
DELETE /movie/:mid
GET /movies/last
GET /movies/similar/:mid
GET /user/:uid/movies/last
GET /user/:uid/movies/suggested
GET /user/:uid/movies/friends
GET /content/:uid/movies

Contents
GET /content/:cid
POST /content
DELETE /content/:cid
GET /movie/:mid/contents
GET /contents/last
GET /contents/similar/:cid
GET /user/:uid/contents/suggested
GET /user/:uid/favourites/last
GET /user/:uid/favourites/movie/:mid
POST /user/:uid/favourite
DELETE /user/:uid/favourite/:fid
GET /user/:uid/shared/last
GET /user/:uid/shared/movie/:mid
POST /user/:uid/shared
DELETE /user/:uid/shared/:fid

Users
GET /user/:uid
POST /user
DELETE /user/:uid
GET /users/friends/:uid
POST /user/:uid/action
POST /user/:uid/tag
GET /user/:uid/tags/movie/:mid
DELETE /user/:uid/tag/:tid

KLIKSEE SOFTWARE REQUIREMENTS SPECIFICATION

"15

Social networks
GET /user/:uid/socialnetworks
POST /user/:uid/socialnetwork
DELETE /user/:uid/socialnetwork

Performance requirements
In order to establish great performance with high number of users expected in the near
future, all the server architecture and implementation must be done with scalability in mind.
Particularly, the database should be horizontally scalable as well as vertically scalable, and the
web server should be stateless and easily scalable by addition of multiple instances.

Use Cases - Application

External player

Register

Play movie
Add Tag
request

<include>

<include>
Open
content
website

KLIKsee
user

Login

Open
sidebar
Open
content shop
website

<extends> <extends>
Social
network
login

<include>

<include>

Forgot
password
Open
settings

<include>

Open
contents
window

Mark
content as
favourite

See tag
requests
status

Share
content
Logout
Add social
networks
account

Filter content:
view all/only favourite

Application
general
settings
Filter content:
by category

"

KLIKSEE SOFTWARE REQUIREMENTS SPECIFICATION

"16

Appendix
Sidebar contents list policy
The sidebar contains a list of content, in inverse chronological order of appearance on the
movie. This section will describe how the contents to be added and their order in the list has
to be selected.
First of all, the list will contain only items that are already been seen on screen, i.e. with
start_time < now. They will be ordered in chronological order by their end_time. This in order to
keep on top of the list the items last seen on the movie. However, some other informations
must be taken into account.
A content can be seen more than once in a movie. To avoid the item to be on top of the list
most of the time the user open the sidebar, the number of times the user see that item while
scrolling the list should be taken into consideration as sort of a penalty for its position. For
instance, lets say an user sees an item that she is interested in now. Even if the item was
already be in the movie for 10 times before the time the user open the sidebar, if she never
saw the item in the list (e.g. because she didnt open the sidebar before) than that item must be
on top of it. On the contrary, if the users has already seen that item for 4-5 times, she could
be annoyed by seeing it again. So a penalty must be choose that take into consideration the
trade off between see something too much, and not seeing it at all when Im actually
interested on it. Different algorithm must be tried to choose the best one to use, but for a start
it could be easily implemented by subtracting a time penalty to the end_time depending on
how many time the user has seen that item in the sidebar.
Moreover, in the case of multiple appearances of an item, it must not be put in the list more
than once, and only the last item appearances must be added to the list.
The following is a self-explanatory pseudocode example of a selection and sorting policy:
all_contents = get_movie_contents()
list_contents = {}
for(Content c in all_contents){
if(c.start_time < now){
if(c.id in list_contents){
c2 = list_contents.get(c.id)
c2.end_time = max(c.end_time, c2.end_time)
}else{
list_contents.add(c)
}
}
}
list_contents.sort_by(function(Content c){
c.end_time - PENALTY * c.number_of_times_on_sidebar
})

KLIKSEE SOFTWARE REQUIREMENTS SPECIFICATION

"17