Developers · Plugin API level 1

Build for Dyla.

Packages add features to Dyla without being part of it. They are downloaded from Dyla’s catalog, loaded into the running app, and removed again without a trace. Dyla’s own News, Podcasts, YouTube and Spotify importers are packages too.

Package SDK on GitHub Coming soon

How it works

  1. Build a Kotlin module against the plugin API
  2. Verify it with Dyla’s verifier
  3. Review by a maintainer, who signs it
  4. Publish to the catalog
  5. Install from Dyla’s Packages screen

A package is compiled code (classes.dex), a manifest, and optional assets and native libraries. On the phone, Dyla checks every byte against the review signature and loads the code with a class loader that sees only the public plugin API: not Dyla’s classes, databases, settings or other packages. Everything a package can do goes through services Dyla hands it, each gated by a capability it declared and the listener accepted. Every call is timed out and guarded; a package that hangs or crashes repeatedly is switched off, and any published version can be revoked remotely.

Packages run in Dyla’s process, so they are instant, need no install prompt and share Dyla’s voices, player and library through fast in-memory calls. A package never draws its own UI: it describes settings and content, and Dyla presents them in the listener’s finish, so every package looks native.

The package

A .dylapkg file is a zip:

plugin.json                 manifest
classes.dex, classes2.dex…  code, compiled against the plugin API only
assets/…                    optional, read through PluginStorage
lib/arm64-v8a/*.so          optional loadable libraries
META-INF/DYLA.MF            path + SHA-256 of every other file
META-INF/DYLA.SIG           ECDSA P-256 signature of DYLA.MF (added at review)

plugin.json

{
  "id": "com.example.podcasts",
  "name": "Podcasts",
  "version": 3,
  "versionName": "1.2.0",
  "apiLevel": 1,
  "entry": "com.example.podcasts.PodcastsPlugin",
  "summary": "Subscribe to podcasts and hear new episodes between songs.",
  "publisher": "Example Labs",
  "license": "Apache-2.0",
  "source": "https://github.com/example/dyla-podcasts",
  "capabilities": ["radio-breaks", "settings"],
  "network": ["feeds.example.com", "*.libsyn.com"],
  "mediaSources": [],
  "nativeLibraries": []
}
  • id is reverse-DNS and never changes. version is an increasing integer.
  • apiLevel is the plugin API level you built against; Dyla loads any level it supports.
  • capabilities, network and mediaSources are the whole of what the package may use. Listeners see them before installing, and Dyla enforces them.
  • network lists the domains your package may contact through PluginHttp, checked on every request and every redirect.
  • mediaSources lists sites whose pages you may hand to Dyla’s media downloader. Your package never contacts them itself, and only a link-import package may declare them.

Entry point

Implement DylaPlugin, plus the interface of each capability you declared. Everything reaches you through PluginContext; a package never touches Android APIs.

class PodcastsPlugin : DylaPlugin, RadioBreakSource {
    private lateinit var host: PluginContext

    override fun onCreate(context: PluginContext) { host = context }
    override fun onDestroy() {}

    override suspend fun nextBreak(): RadioBreak? {
        val feed = host.http.get("https://feeds.example.com/new.json")
        if (!feed.isSuccessful) return null
        return RadioBreak(
            id = "news-42",
            segments = listOf(RadioBreak.Segment(speaker = "Amy", text = "Here's what's new…")),
            attribution = "Example News",
        )
    }
}
interface PluginContext {
    val pluginId: String
    val hostApiLevel: Int
    val http: PluginHttp          // declared domains only
    val storage: PluginStorage    // your own folder, and your assets
    val settings: PluginSettings  // your own key-value settings
    val log: PluginLog
    fun <T : HostService> service(type: Class<T>): T?   // MediaDownloads, LibraryImport, PodcastFeeds
}

Capabilities

CapabilityYou implementYou receive
settingsSettingsSchema: controls Dyla draws in its own stylePluginSettings
radio-breaksRadioBreakSource: short scripts the radio host reads between songs(none)
link-importLinkImporter: turns shared links into songsMediaDownloads (declared mediaSources only), LibraryImport
podcastsPodcastDirectory: categories, browsing, search, shows, episodes, transcriptsPodcastFeeds (reads any show’s RSS, parsed)
(always)(none)PluginHttp, PluginStorage, PluginLog
interface SettingsSchema {
    fun settings(): List<Setting>          // Toggle, Choice, MultiChoice, Text, Action
    suspend fun onAction(key: String) {}
}

interface RadioBreakSource {
    suspend fun nextBreak(): RadioBreak?
    suspend fun refresh() {}
    suspend fun onBreakFinished(breakId: String, heard: Boolean) {}
    val preferredTracksBetweenBreaks: Int get() = 4
}

interface LinkImporter {
    fun canHandle(url: String): Boolean
    suspend fun preview(url: String): ImportPreview
    suspend fun import(url: String, selected: Set<String>, progress: ImportProgress): ImportSummary
}

interface PodcastDirectory {
    suspend fun categories(): List<PodcastCategory>
    suspend fun browse(category: String?, sort: ShowSort, page: Int): PodcastPage<PodcastShow>
    suspend fun searchShows(text: String, page: Int): PodcastPage<PodcastShow>
    suspend fun searchEpisodes(text: String, page: Int): PodcastPage<PodcastEpisode>
    suspend fun show(showId: String): PodcastShow?
    suspend fun episodes(showId: String, page: Int): PodcastPage<PodcastEpisode>
    // optional: trending, suggest, searchTranscripts, summarize, transcript
}

A radio break’s pronunciations map ("Ethiopia" to "Ee-thee-oh-pee-ah") lets you show names as written while the voices say them as respelled. A podcasts package only describes shows and episodes: Dyla streams and downloads the audio and keeps follows and resume positions itself, so swapping directories loses none of the listener’s data.

Services

interface PluginHttp {
    suspend fun get(url: String, headers: Map<String, String> = emptyMap()): HttpResponse
    suspend fun post(url: String, body: ByteArray, contentType: String, headers: Map<String, String> = emptyMap()): HttpResponse
}   // throws NetworkNotAllowedException for undeclared hosts

interface PluginStorage { val filesDir: File; fun openAsset(path: String): InputStream? }
interface PluginSettings { fun get(key: String): String?; fun set(key: String, value: String?); fun all(): Map<String, String> }
interface PluginLog { fun info(message: String); fun warn(message: String, error: Throwable? = null) }

// Host services, through context.service(...)
interface MediaDownloads : HostService {
    suspend fun download(query: String, onProgress: (Float) -> Unit = {}): DownloadedAudio
    suspend fun describe(url: String): MediaListing
}
interface LibraryImport : HostService {
    suspend fun add(audio: DownloadedAudio, metadata: TrackMetadata): ImportedTrack
    suspend fun existing(metadata: TrackMetadata): ImportedTrack?
    suspend fun fileUnderPlaylist(collectionId: String, name: String, artworkUrl: String?, tracks: List<ImportedTrack>)
}
interface PodcastFeeds : HostService {
    suspend fun read(feedUrl: String, offset: Int = 0, limit: Int = 50): PodcastFeed
}

Heavy native tools (the media downloader: Python and ffmpeg) live in Dyla itself and are offered as MediaDownloads: Android does not allow running programs an app downloaded.

Rules

Rejected by the verifier, and blocked at run time where possible:

  • Starting processes (Runtime.exec, ProcessBuilder)
  • Loading further code (DexClassLoader, PathClassLoader, InMemoryDexClassLoader)
  • Reflection outside your package (setAccessible, Class.forName on other classes, sun.misc.Unsafe)
  • Direct network access (Socket, URL.openConnection, OkHttp): use PluginHttp
  • URLs to hosts in neither network nor mediaSources
  • Dyla internals: any com.dyla.* outside com.dyla.plugin.api
  • Android system surfaces: activities, services, receivers, accessibility, package installation, system settings
  • Native executables. Native libraries must be arm64, 16 KB aligned, and import no process or dynamic-loading functions.

Build & verify

Depend on the plugin API as compileOnly: Dyla provides it at run time, with the Kotlin standard library and kotlinx.coroutines. The Gradle plugin compiles to dex and assembles the package from src/main/plugin.json and, optionally, src/main/assets/.

plugins { id("dyla.plugin.package") }

dependencies {
    compileOnly(libs.org.json)   // Android provides org.json and XmlPull: never bundle them
}
./gradlew :plugins:podcasts:dylaPackage   # build/outputs/dylapkg/<id>-<version>-unsigned.dylapkg
./gradlew :plugins:podcasts:dylaVerify    # the full evaluation, contract tests included

The verifier checks the package structure, manifest and size limits; every method reference in your dex against the rules; native libraries; that the interfaces you implement match the capabilities you declare; and loads your package in a test host to drive each capability within time and memory budgets.

Publishing

  1. Submit your package’s source repository.
  2. It is built reproducibly from source, and the verifier runs.
  3. A maintainer reviews the source and the report.
  4. The package is signed with Dyla’s review key and added to the catalog. Listeners find it in Settings, under Packages.

A version found bad after publishing is revoked, and switched off on every phone. The catalog is public: GET https://dyla.knovuslab.com/public/api/plugins.

Versions

The plugin API only grows within a level. Packages construct some API types themselves (RadioBreak, ImportPreview…), and adding a field to a Kotlin data class changes its constructor, so once third-party packages are published a level’s types are frozen and new fields arrive in a new level. Until then, level 1 may still change. A breaking change raises the level; Dyla keeps loading the previous one for as long as practical, and the catalog stops offering packages an installed app cannot load.

Questions, or a package in mind? github.com/m3nd3x