Skip to content

Settings

DRN edited this page Jun 22, 2024 · 22 revisions

IF YOU ARE NOT USING .JSONC MAKE SURE YOU REMOVE ANY // COMMENTS IN THIS DOCUMENTATION.

Important Notes

  • Settings are supported in .JSON, .JSONC (JSON with comment support; // /* */), and .YAML.
  • Settings are case sensitive (follow the same capitalization as this documentation).
  • If using JSON/JSONC, do not leave trailing commas, this will throw errors (Commas after the last item in a section/group).
  • The bot will look for a file named settings that matches .json/.jsonc/.yaml, this can be overrode by passing an argument with the executable. Example in Windows CMD: discord-downloader-go.exe otherSettings will look for otherSettings.json/otherSettings.jsonc/otherSettings.yaml.

If you have a config.ini from Seklfreak's discord-image-downloader-go, when launching with no settings file present, the bot will import settings from discord-image-downloader-go if it's in the same folder as discord-downloader-go.

If you are using .json/.jsonc, the bot will convert to YAML and store in cache/settings.yaml upon launch, for help with conversion if you wish to use YAML. Alternatively, if you are using .yaml, the bot will convert to JSON and store in cache/settings.json upon launch, for help with conversion if you wish to use JSON.

All Settings

Important Notes

Almost all settings are optional. If you remove or omit lines from your settings, they will just assume default values.

Most settings that pertain to sources (channels, servers, etc) will have 2 variants; 1 global default setting (which you can modify in the main section, otherwise default values will be used) and 1 source-specific setting that you can use to selectively override the global default setting.

Example: The bot will do emoji reactions when downloads succeed on channels "a" and "c" but NOT on channel "b".

{
    "reactWhenDownloaded": true,
    "channels": [
        {
            "channel": "a",
            "destination": "a"
        },
        {
            "channel": "b",
            "destination": "b",
            "reactWhenDownloaded": false
        },
        {
            "channel": "c",
            "destination": "c"
        }
    ]
}

All Available Settings + Default Values

{
    "credentials": {
        "token": "YOUR_USER_OR_BOT_TOKEN",        // user with 2FA or genuine Discord bot.
        "email": "YOUR_USER_EMAIL_NO_2FA",        // user without 2FA.
        "password": "YOUR_USER_PASSWORD_NO_2FA",  // user without 2FA.
        "twitterEnabled": true,         // Toggle Twitter / X authentication, enabled by default.
        "twitterUsername": "",          // Twitter / X Account, required to fetch tweet media.
        "twitterPassword": "",          // Twitter / X Account, required to fetch tweet media.
        "twitterProxy": "",                 // OPTIONAL - Connect to Twitter / X via Proxy; Supports HTTP(s) and SOCKS5.
        "instagramEnabled": true,       // Toggle Instagram authentication, enabled by default.
        "instagramUsername": "",        // Instagram Account, captcha required at some point(s).
        "instagramPassword": "",        // Instagram Account, captcha required at some point(s).
        "instagramTOTP": "",            // Instagram Account, TOTP seed for 2FA code generation.
        "instagramProxy": "",               // OPTIONAL - Connect to Instagram via Proxy; Supports HTTP(s) and SOCKS5.
        "instagramProxyInsecure": false,    // OPTIONAL - Define if proxy is insecure connection.
        "instagramProxyForceHTTP2": false,  // OPTIONAL - Define if proxy client should force HTTP2.
        "flickrApiKey": ""
    },

    "admins": [
        "YOUR_DISCORD_USER_ID",
        "YOUR_FRIENDS_DISCORD_USER_ID",
        "YOUR_OTHER_FRIENDS_DISCORD_USER_ID"
    ],
    "adminChannels": [
        {
            "channel": "DISCORD_CHANNEL_ID_FOR_COMMANDS",
            "logProgram": false,      // output most program logging to channel (this is typically a lot)
            "logStatus": true,        // output program status updates to channel
            "logErrors": true,        // output download errors to channel
            "unlockCommands": false   // allow non-admins to use commands in this channel
        }
    ],

    "overwriteCachePath": "",               // "cache" by default
    "overwriteHistoryPath": "",             // "cache/history" by default
    "overwriteDuploPath": "",               // "cache/.duplo" by default
    "overwriteTwitterPath": "",             // "cache/twitter.json" by default
    "overwriteInstagramPath": "",           // "cache/instagram.json" by default
    "overwriteConstantsPath": "",           // "cache/constants.json" by default
    "overwriteDatabasePath": "",            // "database" by default
    "overwriteDatabaseBackupsPath": "",     // "backups" by default

    "logOutput": "",    // optional filepath to log console output to, include extension.
    "logIndent": true,  // indentation between log timestamp/prefix and log content.

    "processLimit": 32, // # of concurrent tasks allowed at once.

    "debug": false,                 // detailed program info.
    "backupDatabaseOnStart": false, // backup database folder to dated zip file in local "backups" folder.
    "watchSettings": true,          // update settings live if file is modified.
    "settingsOutput": true,         // display parsed settings on load.
    "messageOutput": true,          // display messages being processed in real time.
    "messageOutputHistory": false,  // display messages being processed while running history.

    "discordLogLevel": 0,         // discord API log leveling setting.
    "discordTimeout": 180,        // seconds to wait before giving up on a stale Discord connection.
    "downloadTimeout": 60,        // seconds to wait before giving up on a download.
    "downloadRetryMax": 3,        // times to retry a failed download.
    "exitOnBadConnection": false, // kill the program when encountering a faulty Discord connection rather than retrying.
    "githubUpdateChecking": true, // check for program updates on launch.

    "commandPrefix": "ddg ",      // prefix for discord commands.
    "commandTagging": true,       // tag when responding to commands (including history).
    "scanOwnMessages": false,     // checks messages of authenticated user, should be false if genuine bot, true if selfbot.
    "allowGeneralCommands": true, // ping/help/info/etc.
    "inflateDownloadCount": 0,    // +/- displayed download tally.
    "europeanNumbers": false,     // 1.000.000,00 (disgusting) versus 1,000,000.00 (normal).

    "historyManagerRate": 5,  // seconds between reprocessing history queue.
    "checkupRate": 30,        // minutes to print checkup line in program.
    "connectionCheckRate": 5, // minutes to check Discord connection for failure.
    "presenceRefreshRate": 3, // minutes to refresh Discord presence, sometimes it randomly goes blank.

    "save": true,
    "allowCommands": true,  
    "scanEdits": true,
    "ignoreBots": true,

    "sendErrorMessages": false,   // Send error replies in Discord.
    "sendFileToChannel": "",      // Forward detected media to channel.
    "sendFileToChannels": [ "" ], // ^.
    "sendFileDirectly": true,     // Send direct file as attachment or embed in message.
    "sendFileCaption": "",        // Caption to accompany media.

    "filenameDateFormat": "2006-01-02_15-04-05",    // Format for {{date}}.
    "filenameFormat": "{{date}} {{file}}",          // Default would be "2020-01-02_03-04-05 original_filename.png"
    "filepathNormalizeText": false,                 // Normalize diacritics (letter-like symbols/font-characters) to their standard equivalents.
    "filepathStripSymbols": false,                  // Strip symbols.

    "presenceEnabled": true,    // Display Discord presence
    "presenceStatus": "idle", // "online" or "idle" or "dnd" or "invisible".
    "presenceType": 0,        // 0 = Playing, 1 = Streaming, 2 = Listening, 3 = Watching.
    "presenceLabel": "{{timeSavedShort}} - {{countShort}} files",
    "presenceDetails": "{{timeSavedLong}}",       // user accounts only - "3:04:05pm MST - January 2, 2006" by default.
    "presenceDetails": "{{count}} files total",   // user accounts only.

    "emojisServers": [ "123" ],                   // List of servers to download emojis from upon launch.
    "emojisFilenameFormat": "{{ID}} {{name}}",    // These are currently the only data keys for this.
    "emojisDestination": "X:/emojis",             // Sets destination. If this is not included, defaults to bot subfolder "emojis".
    "stickersServers": [ "123" ],                 // List of servers to download stickers from upon launch.
    "stickersFilenameFormat": "{{ID}} {{name}}",  // These are currently the only data keys for this.
    "stickersDestination": "X:/emojis",           // Sets destination. If this is not included, defaults to bot subfolder "stickers".

    "reactWhenDownloaded": false,           // react to messages downloaded from.
    "reactWhenDownloadedEmoji": "",         // specify emoji for reactions, random otherwise.
    "reactWhenDownloadedHistory": false,    // react to messages downloaded from in history jobs.
    "overwriteDefaultReaction": "",         // "✅" by default.
    "historyTyping": true,                  // show user as typing when processing history.
    "embedColor": "",                       // override embed color, role color by default.

    "historyMaxJobs": 3,            // # of history jobs allowed to run concurrently, constrained by processLimit above.
    "autoHistory": false,           // automatically run history on launch.
    "autoHistoryBefore": "",        // YYYY-MM-DD for date filtering.
    "autoHistorySince": "",         // YYYY-MM-DD for date filtering.
    "sendAutoHistoryStatus": false, // send status message for auto history jobs.
    "sendHistoryStatus": true,      // send status message for history jobs.
    "historyRequestCount": 100,     // amount of messages to request per batch when processing history. 100 default, 100 max.
    "historyRequestDelay": 0,       // delay by seconds for history batch requests (each message batch)

    "subfolders": ["{{fileType}}"],
    "saveImages": true,
    "saveVideos": true,
    "saveAudioFiles": true,
    "saveTextFiles": false,
    "saveOtherFiles": false,
    "savePossibleDuplicates": false, // save if exact filename already exists.
    "delayHandling": 0,         // delay link handling by milliseconds for live messages
    "delayHandlingHistory": 0,  // delay link handling by milliseconds for history messages

    "filters": {
      // when "allowed" options are enabled, nothing is allowed unless it meets their criteria.
        "blockedPhrases": [ "" ],
        "allowedPhrases": [ "" ],

        "blockedUsers": [ "" ], // by Discord ID.
        "allowedUsers": [ "" ], // by Discord ID.

        "blockedRoles": [ "" ], // by Discord ID.
        "allowedRoles": [ "" ], // by Discord ID.

        "blockedDomains": [ "" ],
        "allowedDomains": [ "" ],

        "blockedExtensions": [ ".htm", ".html", ".php", ".exe", ".dll", ".bin", ".cmd", ".sh", ".py", ".jar" ],
        "allowedExtensions": [ "" ],

        "blockedFilenames": [ "" ], // List of phrases to check for in original filename, pre-formatting.
        "allowedFilenames": [ "" ],

        "blockedReactions": [ "" ], // List of reactions to block or allow, by ID only.
        "allowedReactions": [ "" ]
    },

    // duplicate image filtering
    // caching of image data is stored via a database file; it will not read all pre-existing images.
    "duplo": false,
    // threshold for what the bot considers too similar of an image comparison score.
    // * lower = more similar (lowest is around -109.7).
    // * higher = less similar (does not really have a maximum, would require your own testing).
    // if score is lower than your threshold, the image will be skipped.
    "duploThreshold": 0,

    "logLinks": {
        "destination": "",
        "subfolders": [ "{{year}}-{{monthNum}}-{{dayOfMonth}}" ],
        "filenameFormat": "{{serverName}} - {{channelName}}.txt",

        "prefix": "[{{serverName}} / {{channelName}}] {{username}} @ {{timestamp}}: ",
        "suffix": "",

        "filterDuplicates": false,
        
        "logDownloads": true,
        "logFailures": true
    },

    "logMessages": {
        "destination": "",
        "subfolders": [ "{{year}}-{{monthNum}}-{{dayOfMonth}}" ],
        "filenameFormat": "{{serverName}} - {{channelName}}.txt",

        "prefix": "[{{serverName}} / {{channelName}}] {{username}} @ {{timestamp}}: ",
        "suffix": "",

        "filterDuplicates": false
    },

    "all": {
        "destination": "FOLLOW_CHANNELS_BELOW_FOR_REST"
    },
    "allBlacklistUsers": [ "" ],
    "allBlacklistServers": [ "" ],
    "allBlacklistCategories": [ "" ],
    "allBlacklistChannels": [ "" ],

    "users": [
        {
            "user": "SOURCE_DISCORD_USER_ID",
            "users": [ "SOURCE_DISCORD_USER_ID" ],
            "destination": "FOLLOW_CHANNELS_BELOW_FOR_REST"
        }
    ],

    "servers": [
        {
            "server": "SOURCE_DISCORD_SERVER_ID",
            "servers": [ "SOURCE_DISCORD_SERVER_ID" ],
            "serverBlacklist": [ "DISCORD_CHANNELS_TO_BLOCK" ],
            "destination": "FOLLOW_CHANNELS_BELOW_FOR_REST"
        }
    ],

    "categories": [
        {
            "category": "SOURCE_DISCORD_CATEGORY_ID",
            "categories": [ "SOURCE_DISCORD_CATEGORY_ID" ],
            "categoryBlacklist": [ "DISCORD_CHANNELS_TO_BLOCK" ],
            "destination": "FOLLOW_CHANNELS_BELOW_FOR_REST"
        }
    ],

    "channels": [
        {
            "channel": "SOURCE_DISCORD_CHANNEL_ID",
            "channels": [ "SOURCE_DISCORD_CHANNEL_ID" ],
            "destination": "files/example-folder",

            "enabled": true,
            "save": true,
            "allowCommands": true,
            "commandPrefix": "ddg ",    // override the global default.
            "scanEdits": true,
            "ignoreBots": true,

            "sendErrorMessages": false,
            "sendFileToChannel": "",
            "sendFileToChannels": [ "" ],
            "sendFileDirectly": true,
            "sendFileCaption": "",

            "filenameDateFormat": "2006-01-02_15-04-05",
            "filenameFormat": "{{date}} {{file}}",
            "filepathNormalizeText": false,                 // Normalize diacritics (letter-like symbols/font-characters) to their standard equivalents.
            "filepathStripSymbols": false,                  // Strip symbols.

            "presenceEnabled": true,
            "reactWhenDownloaded": false,
            "reactWhenDownloadedEmoji": "",
            "reactWhenDownloadedHistory": false,
            "blacklistReactEmojis": [ "" ],
            "historyTyping": true,
            "embedColor": "",

            "autoHistory": false,
            "autoHistoryBefore": "",
            "autoHistorySince": "",
            "sendAutoHistoryStatus": false,
            "sendHistoryStatus": true,

            "subfolders": ["{{fileType}}"],
            "saveImages": true,
            "saveVideos": true,
            "saveAudioFiles": true,
            "saveTextFiles": false,
            "saveOtherFiles": false,
            "savePossibleDuplicates": false,
            "delayHandling": 0,
            "delayHandlingHistory": 0,

            "filters": {
                "blockedPhrases": [ "" ],
                "allowedPhrases": [ "" ],

                "blockedUsers": [ "" ],
                "allowedUsers": [ "" ],

                "blockedRoles": [ "" ],
                "allowedRoles": [ "" ],

                "blockedExtensions": [ ".htm", ".html", ".php", ".exe", ".dll", ".bin", ".cmd", ".sh", ".py", ".jar" ],
                "allowedExtensions": [ "" ],

                "blockedDomains": [ "" ],
                "allowedDomains": [ "" ]
            },

            "duplo": false,
            "duploThreshold": 0,

            "logLinks": {
                "destination": "",
                "subfolders": [ "{{year}}-{{monthNum}}-{{dayOfMonth}}" ],
                "filenameFormat": "{{serverName}} - {{channelName}}.txt",
                "filepathNormalizeText": false, // Normalize diacritics (letter-like symbols/font-characters) to their standard equivalents.
                "filepathStripSymbols": false,  // Strip symbols.

                "prefix": "[{{serverName}} / {{channelName}}] {{username}} @ {{timestamp}}: ",
                "content": "{{link}}", // also accepts {{msgContent}} and {{embedDesc}} for logging the related message upon download.
                "suffix": "",

                "filterDuplicates": false,
                
                "logDownloads": true,
                "logFailures": true
            },

            "logMessages": {
                "destination": "",
                "subfolders": [ "{{year}}-{{monthNum}}-{{dayOfMonth}}" ],
                "filenameFormat": "{{serverName}} - {{channelName}}.txt",
                "filepathNormalizeText": false, // Normalize diacritics (letter-like symbols/font-characters) to their standard equivalents.
                "filepathStripSymbols": false,  // Strip symbols.

                "prefix": "[{{serverName}} / {{channelName}}] {{username}} @ {{timestamp}}: ",
                "content": "{{message}}", // currently only accepts {{message}}
                "suffix": "",

                "filterDuplicates": false
            }

        }

    ]
}

Data Keys

Some settings support an internal system that replaces specific keys with data.

Generic Data Keys

Applies to presenceLabel, presenceDetails, presenceState, filenameFormat, sendFileCaption.

  • presenceLabel default: "{{timeSavedShort}} - {{countShort}} files"
  • presenceDetails default: "{{timeSavedLong}}"
  • presenceState default: "{{count}} files total"
  • filenameFormat default: "{{date}} {{file}}"
  • sendFileCaption empty by default.
Key Value
{{dgVersion}} Discord Go Version; ex: "0.27.0-gg.1"
{{ddgVersion}} Project Version; ex: "2.2.1"
{{apiVersion}} Discord API Version; ex: "9"
{{uptime}} Duration the program has been running, condensed.
{{count}} Download Count, formatted with commas
{{countShort}} Download Count, shortened
{{countNoCommas}} Download Count, no commas
{{numServers}} Number of servers accessible
{{numBoundChannels}} Number of downloadable channels in settings
{{numBoundCategories}} Number of downloadable categories in settings
{{numBoundServers}} Number of downloadable servers in settings
{{numBoundUsers}} Number of downloadable users in settings
{{numAdminChannels}} Number of admin channels in settings
{{numAdmins}} Number of admins in settings
{{timeSavedShort}} Last download time; Format: "3:04pm"
{{timeSavedShortTZ}} Last download time; Format: "3:04pm MST"
{{timeSavedMid}} Last download time; Format: "3:04pm MST 1/2/2006"
{{timeSavedLong}} Last download time; Format: "3:04:05pm MST - January 2, 2006"
{{timeSavedShort24}} Last download time; Format: "15:04"
{{timeSavedShortTZ24}} Last download time; Format: "15:04 MST"
{{timeSavedMid24}} Last download time; Format: "15:04 MST 2/1/2006"
{{timeSavedLong24}} Last download time; Format: "15:04:05 MST - 2 January, 2006"
{{timeNowShort}} Current time; Format: "3:04pm"
{{timeNowShortTZ}} Current time; Format: "3:04pm MST"
{{timeNowMid}} Current time; Format: "3:04pm MST 1/2/2006"
{{timeNowLong}} Current time; Format: "3:04:05pm MST - January 2, 2006"
{{timeNowShort24}} Current time; Format: "15:04"
{{timeNowShortTZ24}} Current time; Format: "15:04 MST"
{{timeNowMid24}} Current time; Format: "15:04 MST 2/1/2006"
{{timeNowLong24}} Current time; Format: "15:04:05 MST - 2 January, 2006"

filenameFormat Data Keys

Also accepts Generic Data Keys above.

Applies only to filenameFormat (default "{{date}} {{file}}").

Key Value
{{date}} Date of message, following filenameDateFormat
{{file}} Original Filename
{{fileType}} File extension
{{fileSize}} Filesize
{{messageID}} Discord Source Message ID
{{attachmentID}} Discord Source Message - File Attachment ID
{{userID}} Discord Source Message Author User ID
{{username}} Discord Source Message Author Username
{{channelID}} Discord Source Message Channel ID
{{channelName}} Discord Source Message Channel Name
{{categoryID}} Discord Source Message Category ID
{{categoryName}} Discord Source Message Category Name
{{serverID}} Discord Source Message Server ID
{{serverName}} Discord Source Message Server Name
{{message}} Discord Source Message Content
{{downloadTime}} Time of download; shorthand
{{downloadTimeLong}} Time of download; extended
{{url}} Download URL
{{domain}} Download URL Domain
{{nanoID}} Randomly generated tiny ID
{{shortID}} Randomly generated short ID

sendFileCaption Data Keys

Also accepts Generic Data Keys above.

Applies only to sendFileCaption (none by default) for use with sendFileToChannel/sendFileToChannels.

Key Value
{{channelID}} Discord Source Message Channel ID
{{channelName}} Discord Source Message Channel Name
{{serverID}} Discord Source Message Server ID

subfolder Data Keys

Applies to subfolders setting globally and per-source. This option does not accept the other data keys.

Key Value
{{serverID}} Discord Source Message Channel ID
{{serverName}} Discord Source Message Channel Name
{{categoryID}} Discord Source Message Category ID
{{categoryName}} Discord Source Message Category Name
{{channelID}} Discord Source Message Channel ID
{{channelName}} Discord Source Message Channel Name
{{userID}} ID of Discord user who sent the message
{{username}} Username of Discord user who sent the message
{{message}} Discord Source Message Content
{{messageID}} Discord Source Message ID
{{fileType}} File type grouping; "images", "videos", "applications", etc
{{year}} Year message was sent (2016+)
{{monthNum}} Month of year message was sent (1-12)
{{dayOfMonth}} Day of month message was sent (1-31)
{{hour}} Hour of day message was sent (0-23)

logLinks & logMessages Data Keys

Applies to subfolders, filenameFormat, linePrefix, lineSuffix WITHIN logLinks and logMessages, globally and per-source.

Key Value
{{year}} Year message was sent (2016+)
{{monthNum}} Month of year message was sent (1-12)
{{dayOfMonth}} Day of month message was sent (1-31)
{{hour}} Hour of day message was sent (0-23)
{{minute}} Minute of hour message was sent (0-59)
{{second}} Second of minute message was sent (0-59)
{{timestamp}} Message timestamp, "2006-01-02 15-04-05" format
{{timestampYYYYMMDD}} Message timestamp, "2006-01-02" format
{{timestampHHMMSS}} Message timestamp, "15-04-05" format
{{messageID}} Discord Source Message ID
{{channelID}} Discord Source Message Channel ID
{{serverID}} Discord Source Message Server ID
{{userID}} ID of Discord user who sent the message
{{username}} Username of Discord user who sent the message
{{userDisc}} User discriminator number of Discord user who sent the message
{{channelName}} Discord Source Message Channel Name
{{channelTopic}} Discord Source Message Channel Topic
{{categoryID}} Discord Source Message Category ID
{{categoryName}} Discord Source Message Category Name
{{threadID}} Discord Source Message Thread ID (if thread)
{{threadName}} Discord Source Message Thread Name (if thread)
{{threadTopic}} Discord Source Message Thread Topic (if thread)
{{forumID}} Discord Source Message Forum ID (if forum)
{{forumName}} Discord Source Message Forum Name (if forum)
{{downloadStatus}} [logLinks ONLY] Short Status of Download
{{downloadStatusLong}} [logLinks ONLY] Long Status of Download
{{downloadFilename}} [logLinks ONLY] Filename of Download
{{downloadExt}} [logLinks ONLY] File Extension of Download
{{downloadPath}} [logLinks ONLY] Save Path for Download