Mobile Application for Streaming Server
Macula Mobile app for Macula servers provides mobile client functionality for smartphones, tablets and phablets. Its functionality range is much wider than that of the Web browser client
You can install the Macula Mobile application from Play Store (for Android users) or iTunes (for iOS users).
Supported OS:
Android 10 and higher;
iOS 12 and higher.
Starting with the Macula Mobile app version 1.19.x you need to have the Macula version 1.23 or higher.
Thin client for macOS has almost identical functionality. It can be downloaded from https://www.gsfcorp.com. Just as Macula Monitor, the mobile and macOS clients are free of charge and do not require any additional license to run. Using these, you can connect to any of your Macula servers, provided that Macula Streaming Server functionality is enabled in their settings, as described earlier.
Below, you will find guidelines on your Macula Mobile configuration and usage.
Getting Started
Install Macula Mobile from the corresponding app store, or by following a link from our website https://www.gsfcorp.com.
Interface Overview
Macula Mobile user interface is mostly intuitive: you can interact with the app by tapping or long tapping the interface elements, and also by swiping.
In the top left corner, you will find the application menu. It contains:
Add server: an option to add a new server connection.
Share servers: an option to share your existing server setup by sending the recipient server settings XML file.
Record camera: a possibility to record offline in-app video for further upload to any server.
Settings: general application settings.
Details about the app version.
After you connect to any server, the application menu will be replaced by server menu containing server-specific resources and actions:
View - columns x rows: channel arrangement for live view.
Events: push notifications from the server.
Bookmarks: channel bookmarks from all available servers.
User buttons: any buttons for the current server.
Stream camera: camera streaming option (device >> server).
log out option.
The server menu also has a submenu 'three-dots (...)' button next to the server name. Apart from the Log out option, it allows you to edit the connection settings (e.g., change the user account) without returning to the server list. The 'three-dots (...)' button is also present in other places within the app, and it offers extra options or actions.
Finally, wherever it is impossible to place the submenu button, a 'hidden' drop-down menu is available. Long tap any channel in the multichannel view to see the available quick actions.
Settings
Tap the 'hamburger' menu button in the top left corner to bring up the main app menu, then tap Settings. The parameters here define global app behavior (for all servers); they are preserved as you upgrade the app but are discarded if you uninstall it.
The settings are logically grouped for your convenience. Tap a category to access the settings:
General
Language: set application interface language here (matches device locale by default)
Date format: set the date presentation format you want the application to use, e.g., YYYY/MM/DD
Time format: set the time presentation format you want the application to use, e.g., HH:MM:SS (24h)
Timezone: choose between your mobile client or connected server time zone
Timeline zoom: Pinch zoom (zoom timeline with two fingers)/Smart zoom (timeline zoom depends on the scrolling speed)
Streaming
Quality preference
Auto: the most appropriate stream will be selected automatically based on the connection
Main: only the first (main) stream, [usually] of a larger resolution will be used for all devices
Secondary: only the secondary stream (substream), [usually] of a smaller resolution will be used for all devices
Display video statistics
ON/OFF: defines if the video stream properties (FPS, bitrate) are shown for both incoming and outgoing streams
Decoder configuration: choose how the incoming streams will be decoded
Hardware and software: software decoders will be used if required (warning: software decoding is battery intensive!)
Hardware only: hardware decoding modules available on your phone will be used automatically (recommended for battery saving)
Per codec configuration: choose decoding settings individually for each of the expected codecs
Icons: descriptive elements overlaying the video
Show battery intensive decoder icon: the icon will appear in case a software decoder is in use
Device camera: settings related to your phone's camera; the first time you open this section, you will be prompted to run camera detection
Camera choice and preferences for the reverse streaming (device >> server) for both live and offline recording modes
Off: choose this if you do not plan to stream the device's video to the server
Camera 1: main mobile device camera (normally, back camera)
Camera 2: secondary camera (normally, front camera with less megapixels)
Resolution/FPS/bitrate/codec preference, microphone ON/OFF
Preview: camera preview with the settings defined above
Detect cameras: allow the app to retrieve your phone's camera configuration (detection may take some time, making the app unresponsive - expected behavior)
Stream device GPS location with video to server: when ON, the video streamed from the device camera will be overlayed with GPS coordinates and the device marker will be displayed on the geo maps, if configured
Offline video: settings for offline video recording (for further upload)
Store offline video: choose whether you want to store the recorded files in the app directory on the internal storage or on the external storage (SD card)
Offline video storage limit: restrict the space available for recordings to 100, 200 or 500 MB, 1, 2, 5, 10 or 20 GB, or unlimited
When no space left: the app can either overwrite the oldest file(s) or stop recording new files
Default video upload server: choose a server every time you upload the video or set one of the configured servers to be the default destination
Device configuration: network and other settings related to your phone (but not directly to its cameras)
Allow app/widgets to use: choose the preferred network type for the app and for the app widgets separately
WiFi only: the app will only connect to the server(s) if it is connected to a wireless network (including servers available via VPN)
WiFi and mobile data: the app will use both wireless networks and enabled data services (3G/4G)
Auto close timeout: interval in minutes
Auto close application: Off, always after timeout, After user inactivity timeout
Widgets: all settings related to the app widgets (application extensions)
Widget update interval: automatically load a new frame every 30 seconds, every 1, 2, 5, 10, or 15 minutes
Allow widgets to use: WiFi only, or both WiFi and 3G/4G
Panic server: choose the default server for streaming (panic buttons are widget-like buttons that can be placed on the home screen; tapping the button will start streaming live video to the pre-defined server (device must be registered on the server)
Set up panic button: suggests to create panic button
When enabling a camera and turning ON sound, you may be asked to confirm permissions for the app to access your phone's camera(s) and microphone. Select YES to grant access to these components if you wish to be able to stream video and audio from your phone to the server and clients connected to it.
To exit, tap the arrow icon in the upper left corner, or use your device's Back button (software or hardware) or gesture.
Add a New Server
Tap the "plus" button in the bottom right corner to create a new server connection. Alternatively, you can also tap the main app menu in the top right corner, and then select Add server. The following parameters should be filled in:
Host: server IP or domain name from your Macula configuration.
Port: HTTP or HTTPS port to use (must match the one configured on the server side), the default HTTP port is 8080.
Username and password: user account credentials to connect to the Macula server (a corresponding permission to connect via mobile must be granted)
Server Name: user-defined connection title (the value from the Host field will be used automatically if you leave this field empty)
Additional options:
Use HTTPS: use HTTPS over TLS instead of plain HTTP (target server must have HTTPS enabled and configured)
Enable event notifications: turn ON push notifications from Macula servers (notifications should
be pre-configured via Events & Actions using the Send event to client action)
Trust all certificates from this session: accept all digital certificates provided by target server (required in case you are using a self-signed certificate on the server side)
Set as startup server: select if you wish to automatically connect to the target server on starting the application. On startup, the app will load server list and try to connect to the selected server automatically
OAuth 2.0: Allows to enable OAuth with external authentication providers.
When you are ready, tap Save to save the settings and exit the dialog box, or tap the "<-" Back to discard the changes and simply go back to the main menu.
To edit the settings for an existing server connection, tap the 'three-dots (...)' menu on the right side next to the server name, and then tap the Edit button that will appear in the drop-down menu. Use the Delete menu option to remove any existing entry.
OAuth 2.0
If you want to use OAuth2.0 as an authentication method, you need to set an authentication provider and OAuth user in the Macula Console and then enable this option in the Macula Mobile. Make sure you are logged into your mobile device with the same user credentials as the user added via Macula Console.
If your Macula Console is set properly, by setting OAuth 2.0 as an authentication method in the Macula Mobile, you will see the notification with available providers at the next logon. Pick one you are going to use and follow the instructions. Depending on your OAuth provider - you may be asked to input a security code or verify your identity by the methods intended by your mobile device account security options.
Live View
Tap your pre-configured server in the list to establish connection. If you are using HTTPS with a self-signed certificate, you will have to confirm that you trust the server certificate.
When you connect to a server, the live view mode is loaded by default. If you have already connected to the selected server previously, the most recent live view layout will appear. Each channel's name will be displayed in the top left corner of the picture, together with video stream properties - codec, bit rate, frame rate and resolution; stream statistics can be turned OFF via app settings (see above).
Tap any camera live view video to switch to the single channel view. Tap the "<-" Back button in the upper left corner to return back to the channel list. In both multi- and single channel view, you can swipe up and down to switch between channels. In the single channel view, they will appear one by one. In the multichannel view, the new portion of channels will be shown.
You can change the multichannel layout by tapping the server menu in the upper left corner > View > choose the desired layout (1x1, 2x1, 2x2, and 3x2 options are available)
Swipe left/right (while holding the device horizontally) or up/down (for vertical mode) to scroll the channels.
You can pinch the picture to zoom IN/OUT (digital zoom). A tiny picture-in-picture preview will appear in the upper left corner of the viewport. Tap it to reset the DPTZ to the 1:1 zoom level. You can navigate around the zoomed-in image by dragging two fingers over the display.
Tap 
in live view and then tap “Select another channel set…” to select local layout in MY SETS or shared layout in VISUAL GROUPS.
Tap any channel to replace the currently displayed layout with a single channel view with extra controls. These are:
Bottom left corner:
Camera icon: take a snapshot. Tap to save the currently displayed frame onto your device. To find your Snapshot on the Android device - go to the Photos app -> Library -> Pictures folder, and on the iOS device you will be able to find the snapshot in the Photos app, in the most recent photos.
Speaker icon: audio IN (from the camera). Tap once to enable incoming audio (the icon will turn blue), tap once again to stop. The icon will only appear if the target channel has sound enabled.
Microphone icon: audio OUT (talk to the remote camera). Tap once to start sending audio back to the camera (the icon will turn blue), tap once again to stop. Note: you do not need to tap and hold the mic icon, like in the regular Macula Monitor application, simply tap once to enable audio streaming. This icon will only appear if the related functionality is available.
Bottom right corner - three dots' menu:
PTZ: toggle PTZ controls (for PTZ capable cameras). While having overlay PTZ controls ON:
tap/long tap inside the sphere to pan and tilt (the closer you tap to the sphere edge, the faster the PTZ speed will be)
tap/long tap the ends of the zoom bar to zoom IN/OUT
PTZ presets: tap to see the list of available PTZ presets; tap any to make camera go to the specified preset
PTZ tours: tap to see the list of available preset tours; tap any to start the tour; tap Stop PTZ Tour to terminate any currently executed tour
Cast to device: tap to cast the current channel to one of the available Chromecast devices
Create bookmark: Create the bookmark and add the title and the description.
Maintain aspect ratio: toggle aspect ratio (original/stretch to fit); the setting is applied to all channels
Tap the picture again to switch to full screen (remove extra controls). You can still swipe up/down (or left/right for landscape screen orientation) to switch between channels.
While in this mode, you can swipe left or right to load previous or next channel in the list. Long tap on the free space (where there is no stream) or on the stream itself (when PTZ controls are OFF) to bring up the list of all available channels: swipe down and up to browse the list, tap any channel to display it.
Server Menu
You can find the server controls in both, the upper-left corner "hamburger" menu and the upper-right corner - three-dots (...) menu. The Left and right menu offers different controls over the server. The left menu offers:
View - columns x rows: tap to open layout selection. The layouts currently available are: 1x1, 2x1, 2x2, 3x2. If a larger layout has been selected, existing channels will be mapped automatically and all the extra slots will appear blank. To add more channels, tap the "Cameras" button and pick one; all the slots will become marked with blue frames, tap any of them to place the new video channel there.
Events: push notifications from the target server (configurable via Event & Action section in Macula Console).
Bookmarks: channel bookmarks from all the available servers.
User buttons: tap a user button to trigger the action assigned to it (see below for details).
Stream camera: send the video stream from your phone's camera back to the Macula server.
Log out option.
You can manage Channel order and create and manage Channel sets by selecting the three-dots (...) menu from the top right corner:
Modify channel set: By marking items in the checkbox list, you can select which Channels to display for the current configuration. To Save or delete your configuration - navigate to the three-dots (...) menu inside the Modify channel set and Save or Delete channel set.
Delete channel set: Delete the current channel set configuration.
Reset channel order: resets order in which channels are represented in the multi-channel view to default order.
Select another channel set: Allows to switch between pre-configured channel sets.
Open single channel: Allows to select and open a particular channel from the channel list.
Maintain aspect ratio: (on/off) allows to enable/disable default aspect ratio for all the channels in the multi-channel view.
Stream Camera
It is possible to send the video captured by your phone's main or front camera back to the Macula server for further live view on other connected clients and also for server-side recording. To do so, you need to add your mobile device to Macula configuration and then confirm it in your app.
First, go to your server configuration via Macula Console, go to the Configuration section and choose Devices from the menu on the left. On the upper panel, click the + New device button in order to create a new device; enter your desired name and set the Model to (Generics) - External Source, then save. Note the value appearing in the Code field: you will need to enter it into your app.
Next, go to your app -> tap Settings in the bottom, find Device Camera in the list and choose your video preferences; the contents of each item may vary depending on your mobile device capabilities:
Device Camera:
Camera -> Configure camera: select which camera to use (primary/secondary), set Codec, Resolution, Bitrate, FPS, and microphone.
Detect cameras: Use this if no cameras are shown in the camera menu item.
GPS: Stream device location with video to server (on/off).
Store offline video: You can pick from the list where to save offline video.
Offline video storage limit: pick from the list how much memory you want to allow for online video.
When no space left: You can decide to overwrite the oldest video or just stop the recording.
Default video upload server: Select to which server to upload the recorded offline videos.
After the camera is set for the streaming - you can start streaming to the server by selecting Server from the Server list, then go to the top-left "hamburger" menu and select Stream camera. You will see the video stream preview and the round button in the bottom-middle part of your device screen. Tap this button and the video will be streamed to the server. The button will change its appearance to the red dot "recording" button. To stop streaming tap on this button.
You can now manage this stream as a usual channel in Macula Console meaning that you can record both video and audio from it, analyze if for motion etc. To remove this entity, simply delete the device via Macula Console.
Panic Button
Once you have registered your phone on the server, you can set up a panic button on your mobile device. This button is placed on your home screen and, when tapped, initiates live streaming to the pre-defined server immediately - you do not need to open the app and search for the server. To set up this panic button, go to the mobile application settings and:
define the panic server where the stream should be sent in the Application main menu -> Settings -> Widgets ->PanicServer.
create a panic button and place it on the home screen.
To create a Panic button on your Android device:
tap and hold on your device home screen, on the free space until the widget dialog appears.
find Macula Mobile widgets in the widget list and expand the menu.
tap and hold the Macula Mobile panic button, then place it on your home screen.
To create a Panic button on the iOS 12 and newer device:
Open your Shortcuts app (https://support.apple.com/en-us/HT208309). You will see the list of existing shortcuts and an option to add a new one. Tap the Create Shortcut button.
Tap Add action, or just locate the app in the Search for Apps and Actions field by entering the mobile app name until it appears in the list. Tap the app icon. You will see the list of actions available for that app: for our mobile application, there will be the Panic Button item.
Tap the Panic Button item. + and ... icons (Add New and Details) will appear.
Tap the three dots (...) Details icon in the upper-right corner to change the panic button icon appearance and name. Tap the Add to Home Screen option to add the shortcut to the home screen. If you don’t add it to the home screen, the shortcut will only be available from the Shortcuts app or from the Today View. Tap Done to exit the shortcut properties. The button will appear in the list as the newly added shortcut.
Tap Done again to finish adding the shortcut. The newly created shortcut will appear in the list in the Shortcuts app and will become available in your Today View (the section that appears when you swipe to the left edge of the screen).
Exit the Shortcuts app. Your Panic Button will appear on the home screen: tap it to start transmitting video to the selected panic server.
Archive Playback
To switch to the playback mode, tap the Live/Archive switch on the top-right corner in the single channel view. You can navigate through the archive playback. In the top-middle of the screen, tap on arrows around the date to move in the steps of the whole day.
In the bottom-middle of the screen, there are standard playback symbols to play or jump to the beginning or the end of the recording, navigate by minutes, or tap on the timeline and provide year, month, date, and time if you know the exact moment you are looking for. The default value for the time step interval is 1 minute. You also can change this interval by holding +1M and -1M for a short time. The list with available time intervals will appear (5 sec, 10 sec, 1 min, 10 min, and 1 hour). Tap on your preferred time step interval to use it with a single tap.
You can adjust the playback speed by tapping the circle with the number and _x_ symbol in the right-bottom corner near the three-dots (...) menu.
In the right part of the screen, there is Main stream/substream indicator. You can tap on it to switch between streams.
You can find additional controls for the navigation inside the three-dots (...) menu in the right-bottom corner of the screen.
Jump to time: allows to pick up the exact date and time for the playback.
Jump to channel events: allows to pick the event directly from the channel event list if any exist.
Jump to channel bookmarks: allows to navigate directly to the bookmark if any exist.
Previous and Next controls: allows to set icons around the Play button to move by frame, bookmark, or Motion event.
Create bookmark: provide an option to add a bookmark with a Title and its description.
Maintain aspect ratio: (on/off) allows to maintain proportions of the video or stretch it to the proportions of the screen.
Widgets
Widgets are information elements that can be placed on the home screen on Android devices and in the Today view on iOS devices. Individual channels that require frequent monitoring can be placed as Macula Mobile widgets with moderate or low (from twice per minute down to four times per hour) refresh rate so that you do not have to open the whole app each time you need to check the channel. For channels accessible via Internet, this means you can monitor them even if you are in a remote location on 3G or 4G: relatively low frame refresh frequency does not use much bandwidth. You can also limit widgets to use WiFi connection only.
General steps to add and use a widget are the following:
add as many widgets as you need, one widget per channel,
go to Macula Mobile app settings and set widget update and network usage preferences (for details, see the Settings section above),
assign channels to widgets.
To add a widget on an Android device:
tap on a blank space on the home screen and hold for a couple of seconds until the menus appear,
tap the Widgets menu at the bottom of the screen, locate Macula Mobile widget and then drag to place it onto the desired place. Widget of default size (2x2 cells) will appear with a Slot not configured message inside:
drag the orange borders to adjust the widget size, then tap outside the widget to exit the adjustment mode (you can change the widget position and size at any time later by long tapping the widget and then moving it)
tap the widget once: Macula Mobile application will open, allowing you to choose the channel,
then, in the Macula Mobile app:
go to the app settings before connecting to the server and choose how frequently the widgets will be refreshed, and also their network usage preference (see the Settings section above for details),
connect to a server of your choice, choose Camera to widget from the main menu, then tap a channel to choose it (all channels will be highlighted with blue frames, swipe left or right to load more channels to choose from), and then choose a widget slot from the list by tapping it, too (the slot may be empty or already contain a channel),
go back to your home screen: the assigned channel should now be present in the widget, with the channel name in the top left corner, slot number in the bottom left corner, and last refresh time in the bottom right corner.
To replace the channel, follow the steps 3-4 above; to remove the widget, simply tap and hold it until the menus appear and then drag and drop it onto the Recycle bin icon. Tapping a widget will result in opening the corresponding app, as described above.
To add a widget on an iOS device:
swipe down over the Home screen, Lock screen or Notification center to bring the Today view screen, scroll to the bottom to reach for the Edit menu, tap Edit,
locate the Macula Mobile app and tap (+) sign to the left of it: the app will be added to the list above,
tap Done when you have finished; the widget will appear under Widgets, allowing you to add and resize the slots - tap any slot to open the Macula Mobile app,
then, in the Macula Mobile app:
go to the app settings before connecting to the server and choose how frequently the widgets will be refreshed, and also their network usage preference (see the Settings section above for details),
connect to a server of your choice, choose Camera to widget
from the main menu, then tap a channel to choose it (all channels will be highlighted with blue frames, swipe left or right to load more channels to choose from), and then choose a widget slot from the list by tapping it, too (the slot may be empty or already contain a channel),
go back to your Today view: the assigned channel should now be present in the widget, with the channel name in the top left corner, slot number in the bottom left corner, and last refresh time in the bottom right corner.
You can drag widgets to rearrange them in the Today view; tapping a widget will open the associated app. To remove a widget, go back to the widget list in the Today view, as described above, and tap the (-) sign next to the Macula Mobile name, then tap the Remove button. If you remove the widget and then add it anew, it will retain its view (slots).
User Buttons
User buttons are software buttons, controls used in Macula Monitor and for manual event triggering: upon clicking or tapping a user button, the action associated with it is triggered. The action, the user button itself and the rule that makes the user button work are all pre-configured via Macula Console; see corresponding sections of the server management manual for details.
If you are connected to a server that has configured user buttons and your user account has permissions to use them, the buttons will be available in the app. To access them, tap the main menu and choose 
.Then, choose the button you want to use and tap it: the associated action will be triggered and you will receive a confirmation in the bottom of the screen.
Events
Macula Mobile app allows you to receive push notifications from the Macula server once they have been set up via Macula Console Event & Action management.
In order to do this, create an action of the Send event to client type via Macula Console and enable the Display event in mobile application option, then attach this action to your desired event in the Rules section. When creating the rule, do not forget to set the target channel for it: the notifications will appear for that particular channel and their availability can be controlled via channel access permissions. It is possible to limit the reception of the notifications to certain user profile or user group. You will find more details on how this is done in the Events & Actions section, under Actions.
Triggered notifications will immediately appear on the mobile device(s) that have Macula Mobile app installed with the target Macula server configured (connected user account must have permissions for the target channel). The app itself may be not running: events will pop up as regular text message notifications. If the target mobile device is offline, the notifications will arrive shortly after it re-connects to a network that provides required server connection.
Offline Camera
Starting from version 1.7, Macula Mobile allows you to record offline video clips for further upload to the server. The video can be recorded from the device camera in the app and stored as long as required until the server connection is available.
To enable this, you first need to:
set up the target server connection in the app
choose your camera preferences
register your smart device on the Macula server as External Model as you would do for live streaming from device camera
enable Edge Recording for the newly created channel
You only have to do this once for each device (unless you re-install the app). From then on, you will be able to record as many video clips as you wish, and then upload them to the target server.
If you do the have your device paired with the server yet, go to your Macula server configuration via Macula Console, go to the Configuration section and choose Devices from the menu on the left. On the upper panel, click the + New device button in order to create a new device; enter your desired name and set the Model to (Generics) - External Source, then save. Note the value appearing in the Code field: you will need to enter it into your app.
Next, go to your app -> server list -> tap Settings in the bottom, find Camera in the list and choose your video preferences; the contents of each item may vary depending on your mobile device capabilities:
Camera: back/front (primary/secondary)
Resolution: [the actual list depends on the mobile device capabilities]
Bitrate: Video bitrate
FPS: from 10 up to max allowed by device
Camera Microphone: disable/enable sound
To start offline recording - go to the Channel list, tap on the top-left corner "hamburger" menu, and select the Record camera.
Rotate your device the way you want to hold it during the process and tap the Start recording button: it will turn red indicating that the recording is happening. Tap it again to stop: a new file will appear in the list and the camera preview will return to live.
In the right-bottom corner of the screen - tap the Archive button. You will find the list of the offline recordings. To replay the recording - tap on the recording you want to replay. The video file(s) will be uploaded to the selected Macula server and stored as an edge stream for your device's channel. Do not worry if the upload is interrupted due to network issues: the upload will resume as soon as the connection to the target server is available again.
GPS Tracking
Starting from the Macula Mobile version 1.7 and Macula version 1.8.0, it is possible to send the GPS coordinates of the smart device to the Macula server. The coordinates are then displayed on top of the live and recorded video, and they are also used to trace the device on geo maps.
Setup:
enable sending of GPS data in your app settings
register your device on the server as described above in the Stream Camera/Offline Camera sections so that it exists in the server device/channel configuration
create a geo map on the server via Macula Console
place a camera marker on the map, set your smart device as the target channel and enable tracking in the properties
Now, if you move and stream video from your phone to the Macula server, the marker on the map will move as well, displaying your location. GPS coordinates will be also shown on top of the live video stream and also when it is played back. Note that for the offline recorded stream (clips recorded and then uploaded to the server) the coordinates will not be displayed.
Last updated