How Substratum Brought Fluid & Simple Customization to a Complex TouchWiz

How Substratum Brought Fluid & Simple Customization to a Complex TouchWiz

Android theming has come a long way, from hacky edits to Substratum and now, Sungstratum. Years back, the word “theme” in Android discussions was frequently superseded by the word “chooser’, a nod to the T-Mobile Theme Chooser found in CyanogenMod that laid the foundations that made Android a themer’s paradise. The ability to modify the appearance of the OS granted users another dimension of customization, allowing them to make changes that make their devices a lot more personalized.

The good work continued on in two different directions. The Theme Chooser evolved into the CyanogenMod Theme Engine, but despite the years of efforts put into theming resources, the CMTE became obsolete when other alternatives popped up.


RRO & Layers

The foundation of one of the alternatives was laid down when Sony’s code contribution in the form of the new framework called Runtime Resource Overlay (RRO) was accepted into AOSP. This framework provides the ability to replace application resources during runtime (hence the name). “Overlays” by themselves have been present and supported in Android from as early as Gingerbread (and perhaps earlier as well), used primarily to swap out resources to make applications work on that specific device. Sony’s approach to RRO involved modifying the asset manager to accepts apks which used resources mapped to other corresponding resources existing on the device. These new resources from the apk were then overlaid on top of base resources at runtime only, allowing the system to work along as if these new resources had always been a part of it.

The RRO framework was merged into AOSP before Lollipop 5.0 was made public, but the initial few builds of 5.0 had parts of the framework broken because of other changes. Android 6.0 Marshmallow’s Developer Previews were the first to add in a functional albeit limited RRO framework, opening the doors of customizability right at the stock Android level. So unless an OEM deliberately attempted to diverge from the stock Android theming options, a certain level of consistency could be retained in the approach of how ‘themes’ would be implemented in Android.

While AOSP was toying with RRO and looking at the best way to incorporate it all, a team of developers called BitSyko worked together on a collective effort called “Layers“. Layers expanded upon the stock RRO functionality in Android 5.1 Lollipop to enable more complex resource switching and allowing more element control for themes than possible with stock RRO. Because Layers built upwards on RRO, ROM makers needed to add in extra code to enable Layers functionality in their ROMs as not all Layers themes would work on stock RRO in Marshmallow.

Meanwhile, Sony marched on with its own efforts towards Android theming. It began working on OMS (Overlay Manager Service), a client for managing overlays that would allow providers to dynamically control priorities and enable and disable overlays. OMS is being merged into AOSP and will make its way into Android O. XDA Recognized Developer nicholaschum was able to confirm through his sources that Android O will sport “dynamic overlays”, which is believed to be a reference to OMS.

OMS caused conflicts with Layers, as traditionally, such functions were under the control of the themer. In order to deal with the issues brought up by OMS as well as to expand upon the functionality of Layers, BitSyko teamed up again (and renamed themselves to [projekt.]) to create Substratum. Substratum is a client with OMS functionality that tries to reconcile the Layers functionality with OMS, and also borrows other elements from other past theming solutions. Overlays were no longer overlapped over each other to theme individual elements, as now, all needed elements were injected into a single overlay. Features like compile-on-device allowed themes to be applied without needing a reboot between changes, making it significantly easier for end users to try out themes and experiment. Substratum has been under active development since its inception, and listing out all of its features and added functionality would be out of the scope of this article, so we’ll move on to the real subject of this piece.


Substratum into Sungstratum

As explained in the previous section, Substratum began as a way to extend stock OMS functionality as well as stock RRO functionality (through Layers). Substratum was intended to be used alongside AOSP-based ROMs, as most other OEMs would have made conflicting changes that would not allow Substratum to co-exist with their modifications on an edited UX skin, such as Samsung’s for example.

Samsung, by itself, was also working on a theming solution for use across its own devices on Nougat. Unlike Sony, Samsung showed no interest in contributing back the theming code to AOSP. But since Samsung’s solution was fairly basic, AOSP was not really losing out on much. Samsung’s theming solution baked into Touchwiz made its real appearance on the Samsung Galaxy S6, but as mentioned, it was fairly restricted in what it could try to achieve. Before that, there was limited experimenting that began with the Galaxy Alpha, though most system UI elements were outside its scope. Themes could change wallpapers and icons as well as a few Samsung stock apps such as the dialer, contacts, messages and the notification area, for example.

As it turns out, Samsung’s theming engine extends RRO as found in AOSP. Samsung also recreated their own internal version of OMS after extending RRO, so their implementations of both RRO and OMS differ from AOSP. But surprisingly, by not a very large amount — an anomalous behavior when one considers the distinctiveness and complexity of Touchwiz. Themers using newer Samsung flagships reported that they could install RRO overlays and have them theme third party applications.

This was the cue that team [projekt.] needed to look into officially supporting Samsung devices on Substratum. The team converted a small amount of code from their RRO/Legacy section of their app, but instead of requesting root and asking to reboot, they fired specific intents so that the overlays are installed. The team then worked to ensure that the applications affected through the themes were force-closed in the background so as to ensure a full asset refresh on the next launch.

We asked XDA Recognized Developer nicholaschum to provide us with some insights into the challenges the team faced when working against Samsung’s closed source implementation of RRO-OMS:

The challenges we faced were rather obscure and unknown by many who do not have much knowledge understanding theming systems, whether open sourced or closed sourced – everything has it’s own trial and error phase. In this case, working with Samsung, I stumbled upon many issues but the main one being system intents not being fired for overlays after installation is complete – such as utilizing broadcast receivers with “android.intent.action.PACKAGE_ADDED” – the Theme Service denies anything that isn’t part of the system signature with a specific Samsung theme service permission from receiving that, so the hardest part is the workarounds that we had to find a way around.

The way we use Substratum alongside Samsung’s Theme Engine is by utilizing the same system as they do. They use a highly modified version of Sony’s Resource Runtime Overlay system, abbreviated as RRO or known as legacy amongst Substratum users. However, what differs is that Samsung themes have an extra permission which hides these overlays from Settings, so you can’t uninstall them one by one manually. We use the same system however we utilize AOSP’s/Sony’s implementation, which is why Samsung Themes can fully theme framework, while Substratum overlays cannot touch a mediator target that doesn’t exist “fwk” – as we all know framework is just “android” package name.

It seemed strange that [projekt.] was able to work alongside Samsung’s RRO implementation with relative ease. Anyone who has ever worked on Samsung devices can attest how difficult Samsung often makes things. We inquired for any specific block that the team encountered during their port:

There is indeed some sort of security mechanism in place that affected a few users – where overlays reverts at start up. This is due to the way Samsung boots up their device. As we are mostly all on 7.0 on TouchWiz/Samsung Experience, we use a new method of “Optimizing apps” (you are able to see this when you update your phone, it will show a notification with the Android Nougat icon, saying that it is upgrading in the background), so this way of optimizing apps also unloads target packages, ultimately disrupting the idmapping process at boot (due to target package not existing) and thus, a few people experience overlay unloads after a reboot.

You can also see this happening with a few Samsung Themes too, particularly @envy~’s Dark/Black theme – he makes the default nav bar color in Display -> Navigation bar to black, where the actual default color is white. After setting it to black, you are able to open the keyboard and the navigation bar stays black. This will get reverted randomly at reboot as well on many devices.

With theming gaining back its prominence, what are Substratum’s plans ahead on the side branches like Sungstratum?

Road ahead, we will be merging a small little app into our addon for our current users so that they will be able to stop Samsung Theme Service if all the themes installed on their devices are installed from XDA. So the people who will be using Samsung-theme-formatted themes from XDA, you will be able to use the addon to prevent Samsung’s service from reverting it back to stock theme after every reboot (because it was not installed from Samsung store officially). It will require a free Samsung developer key available to be obtained from their site, but it’ll be pre-bundled with sungstratum addon download.


With recent and upcoming changes in AOSP and Android O, it looks like Google’s once-fledgling OS will have even more personalization being passed onto the user. Certain OEMs are even planning to get rid of their custom user interfaces and UX additons in favor of AOSP, and others like Samsung hover close enough with their own theming solutions. We envisage a future where themes play a major role in the user experience of even more people– an OS where you truly control how your device looks, where the user interface aesthetics are tailored by you for you. And we wouldn’t be able to reach such a future without the collective power of this awesome community, and projects like Substratum.


Check out Substratum Integration for Samsung Nougat in our Substratum forums! Substratum on GitHub

Discuss This Story

Want more posts like this delivered to your inbox? Enter your email to be subscribed to our newsletter.

READ THIS NEXT