📸 LOCAlbum – Offline Photo Album

🚀 v1.5 — Smart Update Edition (Frozen Folders)

---

🆕 Novidades da versão 1.5 / What's new in v1.5

⚡ Frozen Folders — Atualização instantânea / Instant updates

🇵🇹 O sistema de atualização do álbum (opção 2) foi completamente optimizado. Cada pasta de mês fica agora "congelada" após ser processada. Nas execuções seguintes, pastas sem alterações são ignoradas — apenas as pastas com fotos novas são intervencionadas.

Ao escolher a opção 2, o utilizador pode agora escolher entre:

• [A] Atualização rápida — usa o cache de pastas (recomendado se usaste sempre a opção [1] para adicionar fotos/vídeos)
• [B] Atualização completa — volta a fazer scan a tudo (recomendado se adicionaste ou alteraste fotos/vídeos manualmente nas pastas diretamente no Explorer)

🇬🇧 The album update system (option 2) has been completely optimized. Each month folder is now "frozen" after being processed. On subsequent runs, unchanged folders are skipped — only folders with new photos are rescanned.

When choosing option 2, the user can now select:

• [A] Quick update — uses folder cache (recommended if you always used option [1] to add photos)
• [B] Full update — rescans everything (recommended if you added photos/videos manually in Explorer)

---

🇵🇹 Apresentação

LOCAlbum é uma aplicação leve e totalmente offline que transforma as tuas pastas de fotos num álbum moderno, rápido e organizado por anos e meses, com suporte nativo a fotos e vídeos, slideshow, temas e cálculo opcional de idade.

Ideal para pais que querem registar as memórias dos filhos desde o nascimento.

---

🇬🇧 Overview

LOCAlbum is a lightweight and completely offline application that converts your photo folders into a modern, fast, and interactive album organized by year and month, supporting photos and videos, themes, slideshow, and optional age calculation.

Perfect for parents capturing their children's growth and memories.

✨ Highlights / Destaques

🇬🇧 Highlights	🇵🇹 Destaques
🗂️ Automatic organization by year and month	🗂️ Organização automática por ano e mês
🖼️ Support for photos and videos	🖼️ Suporte para fotos e vídeos
⏱️ Automatic slideshow with adjustable speed	⏱️ Slideshow automático com velocidade ajustável
👶 Optional age display based on birthdate	👶 Cálculo de idade opcional (a partir da data de nascimento)
💾 Works completely offline — no internet needed	💾 Funciona totalmente offline — nada é enviado para a internet
🔄 Unified in one tool: LOCALBUM - Manager.bat	🔄 Tudo num único ficheiro: LOCALBUM - Manager.bat
🌍 Bilingual interface (PT/EN)	🌍 Interface bilingue (PT/EN)

---

🚀 Como usar / How to use

🇵🇹 Passos

1. 📦 Descarrega o projeto completo através do botão verde “Code → Download ZIP” no topo da página e extrai-o para a raiz de um disco ou pen USB
   (ex.: C:\Album\ ou E:\Album\).

   ⚠️ Importante: o projeto deve estar diretamente na raiz, não dentro de subpastas.

2. ▶️ Executa o ficheiro LOCALBUM - Manager.bat.

   • Este é agora o único ficheiro necessário: todas as funções estão reunidas aqui.
   • Ao abrir, escolhe o idioma (Português / English).
   • O menu principal mostra quatro opções:

     [1] Organizar fotos automaticamente
     [2] Atualizar / Criar álbum (HTML)
     [3] Repor / Resetar o álbum
     [i] Informações / Ajuda
     [0] Sair
     

     💡 A opção [i] mostra explicações detalhadas sobre cada função.

3. 📁 Organiza e cria o teu álbum:

• [1] organiza automaticamente milhares de fotos por pastas Ano/Mês (sem duplicados).
• [2] cria ou atualiza o álbum HTML (Ver album.html / View album.html).

  🔍 Nota: Se existirem muitas fotos, este processo pode demorar um pouco na primeira execução devido à criação das thumbnails.
  ⚡ A partir da segunda execução será quase instantâneo graças ao sistema de pastas congeladas — só processa pastas com fotos novas.

• [3] repõe o projeto ao estado original, sem apagar as tuas fotos.
• [i] mostra ajuda e instruções.

4. 💾 O ficheiro Ver album.html será criado automaticamente ao lado da pasta Album/.

5. 🌐 Abre o ficheiro Ver album.html (ou View album.html) no navegador
   (Chrome, Edge, Firefox, etc.).

6. 🎨 Escolhe o tema, vê as fotos e guarda as tuas preferências.

---

🇬🇧 Steps

1. 📦 Download the full project using the green “Code → Download ZIP” button at the top of this page and extract it to the root of a drive or USB stick
   (e.g., C:\Album\ or E:\Album\).

   ⚠️ Important: the project must be placed directly in the drive root — not inside subfolders.

2. ▶️ Run the file LOCALBUM - Manager.bat.

   • This is now the only file you need — all functions are unified here.
   • When it opens, choose your language (Portuguese / English).
   • The main menu offers four options:

     [1] Auto-organize photos
     [2] Update / Create album (HTML)
     [3] Reset album
     [i] Information / Help
     [0] Exit
     

     💡 Option [i] displays detailed explanations about each feature.

3. 📁 Organize and generate your album:

• [1] automatically sorts thousands of photos into Year/Month folders (no duplicates).
• [2] creates or updates the HTML album (View album.html / Ver album.html).

  🔍 Note: If you have many photos, the first run may take a while because thumbnails must be created.
  ⚡ From the second run onwards, updates are nearly instant thanks to the frozen folders system — only folders with new photos are rescanned.

• [3] resets the project to its original state, without deleting your photos.
• [i] displays help and instructions.

4. 💾 The file View album.html will be automatically created next to the Album/ folder.

5. 🌐 Open the file View album.html (or Ver album.html) in your browser
   (Chrome, Edge, Firefox, etc.).

6. 🎨 Pick your favorite theme, browse your photos, and enjoy your offline album.

---

📁 Estrutura de Pastas / Folder Structure

X:
└── Album
      ├── Fotos
            ├── 2023
            ├── Janeiro
                   ├── _frozen.flag    (oculto / hidden — criado automaticamente)
                   └── _cache_mes.json (oculto / hidden — criado automaticamente)
      ├── Thumbnails (hidden) ← (criado automaticamente / automatically created )
      ├── config (oculto / hidden)
      ├── exiftool.exe (oculto / hidden)
      ├── FFmpeg.exe (oculto / hidden)
      ├── localbum-cache.json (oculto / hidden)
      ├── LOCALBUM - Manager.bat ← (ficheiro principal / main file)
      ├── ajuda_album.png (oculto / hidden) 
      ├── favicon.png (oculto / hidden)
      ├── template.html (oculto / hidden)
      ├── z1.ps1, z3.ps1 (ocultos / hidden)
└── Ver album.html / View album.html

🪄 🇵🇹 Após a primeira execução, os ficheiros técnicos são ocultados automaticamente,
restando apenas o LOCALBUM - Manager.bat visível — simples, limpo e pronto a usar.

🪄 🇬🇧 After the first run, all technical files are automatically hidden,
leaving only the LOCALBUM - Manager.bat visible — clean, simple, and ready to use.

---

🛠️ Ferramentas Auxiliares / Helper Tools

🇵🇹 Português

• exiftool.exe (Incluído) — Utilitário desenvolvido por Phil Harvey. Serve para melhorar e otimizar a leitura de metadados e datas cronológicas em formatos menos comuns.
• FFmpeg.exe (Incluído) — Utilitário essencial utilizado em pano de fundo pelo sistema para o processamento rápido e a geração automática de miniaturas (thumbnails) do teu álbum.

🇬🇧 English

• exiftool.exe (Included) — Utility developed by Phil Harvey. It improves and optimizes date and metadata reading for less common media formats.
• FFmpeg.exe (Included) — Essential core utility used under the hood for processing and automatically generating the album thumbnails.

---

🧠 Dicas e Cuidados / Tips & Notes

🇵🇹 Português

• 📁 A pasta principal é aquela onde estão todos os ficheiros do LOCAlbum — por exemplo:

X:
└── Album
      ├── Fotos
            ├── 2023
            ├── Janeiro
                   ├── _frozen.flag    (oculto / hidden — criado automaticamente)
                   └── _cache_mes.json (oculto / hidden — criado automaticamente)
      ├── Thumbnails (hidden) ← (criado automaticamente / automatically created )
      ├── config (oculto / hidden)
      ├── exiftool.exe (oculto / hidden)
      ├── FFmpeg.exe (oculto / hidden)
      ├── localbum-cache.json (oculto / hidden)
      ├── LOCALBUM - Manager.bat ← (ficheiro principal / main file)
      ├── ajuda_album.png (oculto / hidden) 
      ├── favicon.png (oculto / hidden)
      ├── template.html (oculto / hidden)
      ├── z1.ps1, z3.ps1 (ocultos / hidden)
└── Ver album.html / View album.html

🇵🇹 Português

• Não alteres nem renomes:

  • a pasta Fotos/
  • template.html
  • config.ini
  • z1.ps1 e z3.ps1

• Funciona em:

  • Windows (total suporte)
  • macOS / Linux (visualização do HTML)
  • TVs / Tablets (qualquer navegador)

---

🇬🇧 English

• Do not rename:

  • the Fotos/ folder
  • template.html
  • config.ini
  • z1.ps1, z3.ps1

• Works on:

  • Windows (full support)
  • macOS / Linux (HTML viewing)
  • Smart TVs and tablets

---

• ⚙️ O ficheiro config.ini é criado automaticamente e deve permanecer oculto.
• 💾 Podes copiar o projeto completo (pasta Album) para uma pen USB ou disco externo —
  funciona em qualquer PC com Windows, e também em Smart TVs / macOS / Linux.
• 🌐 O álbum funciona totalmente offline, mas o navegador deve permitir abrir ficheiros locais (file://).

---

🇬🇧 English

• 📁 The main folder is the one containing all LOCAlbum files — for example:

X:
└── Album
      ├── Fotos
            ├── 2023
            ├── Janeiro
                   ├── _frozen.flag    (oculto / hidden — criado automaticamente)
                   └── _cache_mes.json (oculto / hidden — criado automaticamente)
      ├── Thumbnails (hidden) ← (criado automaticamente / automatically created )
      ├── config (oculto / hidden)
      ├── exiftool.exe (oculto / hidden)
      ├── FFmpeg.exe (oculto / hidden)
      ├── localbum-cache.json (oculto / hidden)
      ├── LOCALBUM - Manager.bat ← (ficheiro principal / main file)
      ├── ajuda_album.png (oculto / hidden) 
      ├── favicon.png (oculto / hidden)
      ├── template.html (oculto / hidden)
      ├── z1.ps1, z3.ps1 (ocultos / hidden)
└── Ver album.html / View album.html

• 🚫 Do not rename or move the following folders/files:

  • Fotos/
  • template.html
  • config.ini
  • z1.ps1, z3.ps1

• ⚙️ The config.ini file is generated automatically and should remain hidden.

• 💾 You can copy the whole project (the Album folder) to a USB stick or external drive —
  it works on any Windows PC, and also on Smart TVs / macOS / Linux.

• 🌐 The album works entirely offline, but your browser must allow opening local files (file://).

---

📺 Compatibilidade com Smart TVs / Smart TV Compatibility

🇵🇹 Português

Atenção: a maioria das Smart TVs não consegue abrir ficheiros HTML diretamente de uma pen/disco USB.
Isto não é uma limitação do LOCALBUM — é algo comum nas apps de navegador das TVs, que normalmente bloqueiam:

• ficheiros locais (file://)
• JavaScript local
• acesso a imagens/vídeos via HTML quando está offline
• caminhos do dispositivo USB dentro do navegador

Por esse motivo, o ficheiro Ver album.html / View album.html pode não funcionar na TV.

✔️ Mas o álbum continua totalmente utilizável na TV

Mesmo que a versão HTML não abra, todas as TVs conseguem navegar pelas fotos na pasta organizada pelo LOCALBUM:

Album
 └── Fotos
       ├── 2023
       │     ├── Janeiro
       │     ├── Fevereiro
       │     └── ...
       ├── 2024
       │     ├── Março
       │     ├── Julho
       │     └── ...
       └── ...

O LOCALBUM cria automaticamente uma estrutura Ano → Mês, compatível com:

• Smart TVs (Samsung, LG, Sony, TCL, Philips…)
• Android TV / Google TV
• Fire Stick
• Boxes Android
• Consolas
• Media players USB

📌 O que a Smart TV consegue fazer

• Abrir fotos diretamente da pen/disco
• Navegar por Ano → Mês → Foto
• Criar slideshow nativo da TV
• Reproduzir vídeos (MP4/MOV) diretamente das pastas
• Funciona 100% offline, sem browser

📌 Conclusão

Mesmo que a tua TV não suporte o HTML, podes sempre usar a pasta Album/Fotos como uma versão “TV-ready”, totalmente compatível com qualquer dispositivo.

---

🇬🇧 English

Note: most Smart TVs cannot open HTML files directly from a USB drive.
This is not a limitation of LOCALBUM but of TV web browsers, which usually block:

• local file:// access
• local JavaScript
• loading images/videos from HTML pages offline
• USB drive paths inside the browser

As a result, View album.html / Ver album.html may NOT work on a Smart TV.

✔️ But the album is still fully usable on any Smart TV

Even if the HTML viewer doesn’t work, all TVs can browse the photo folder structure created by LOCALBUM:

Album
 └── Fotos
       ├── 2023
       │     ├── January
       │     ├── February
       │     └── ...
       ├── 2024
       │     ├── March
       │     ├── July
       │     └── ...
       └── ...

LOCALBUM automatically organizes photos/videos into Year → Month, which is supported by:

• Smart TVs (Samsung, LG, Sony, TCL, Philips…)
• Android TV / Google TV
• Fire Stick
• Android media boxes
• Game consoles
• Any USB media player

📌 What the Smart TV CAN do

• Open the USB drive and enter the Album/Fotos folder
• Browse Year → Month → Photo
• Display photos in a slideshow
• Play videos (MP4/MOV) natively
• No browser or internet required

📌 Summary

Even if your TV cannot open HTML, LOCALBUM always provides a TV-friendly version through the Album/Fotos folder structure, ensuring full compatibility everywhere.

---

🖼️ Screenshots / Capturas de ecrã

Álbum — primeiros dias de vida / Album — first days of life

Álbum — navegação por ano e mês, separadores de dia, contador de idade / Album — year/month navigation, day separators, age counter

Pasta limpa + menu do Manager / Clean folder + Manager menu

---

⚠️ Nota sobre Antivírus / Antivirus Notice

🇵🇹
Alguns antivírus ou o Microsoft Defender podem mostrar um aviso falso ao abrir o ficheiro LOCALBUM - Manager.bat.
Isto acontece porque o Windows reconhece scripts .bat como “automatizações do sistema”.
🔒 O LOCALBUM é 100% seguro — não se liga à Internet, não altera o sistema e não contém código malicioso.

💡 Podes verificar o conteúdo do ficheiro em qualquer editor de texto (como o Notepad) — é totalmente transparente e legível.
Nenhuma informação é enviada para fora do teu computador.

🇬🇧
Some antivirus programs or Microsoft Defender may show a false alert when opening the LOCALBUM - Manager.bat file.
This happens because Windows often flags .bat scripts as “system automation tools.”
🔒 LOCALBUM is 100% safe — it runs fully offline, does not modify your system, and contains no malicious code.

💡 You can open the file with any text editor (like Notepad) to check its contents — it’s completely transparent and human-readable.
No information is ever sent outside your computer.

---

💝 Apoia o projeto / Support the project

Se este projeto te foi útil, considera apoiar o desenvolvimento.
If this project was useful to you, consider supporting its development.

---

🧑‍💻 Autor / Author

Desenvolvido por Rúben Silva
📧 GitHub Profile
📸 Projeto: LOCAlbum - Offline Photo Album

💡 Because your memories deserve a place — even without internet.

---

📜 Licença / License

Distribuído sob a licença MIT — uso livre, com crédito ao autor.
Distributed under the MIT License — free to use, with author attribution.

⚖️ Softwares de Terceiros / Third-Party Software

🇵🇹 O LOCAlbum depende de excelentes ferramentas de código aberto desenvolvidas pela comunidade. Este projeto inclui e distribui ou suporta os seguintes utilitários sob as suas respetivas licenças originais:

• ExifTool (por Phil Harvey) — Utilitário multiplataforma de leitura e escrita de metadados. Disponível em: exiftool.org (Licenciado sob os mesmos termos do Perl: Artistic License / GPL).
• FFmpeg — Solução completa e multiplataforma para processamento e gravação de áudio e vídeo. Disponível em: ffmpeg.org (Licenciado sob a GNU Lesser General Public License - LGPLv2.1+). Os binários disponibilizados são builds estáticos oficiais de uso livre.

🇬🇧 LOCAlbum relies on excellent open-source tools developed by the community. This project includes, distributes, or supports the following utilities under their respective original licenses:

• ExifTool (by Phil Harvey) — A cross-platform utility for reading and writing metadata. Available at: exiftool.org (Licensed under the same terms as Perl: Artistic License / GPL).
• FFmpeg — A complete, cross-platform solution to record, convert, and stream audio and video. Available at: ffmpeg.org (Licensed under the GNU Lesser General Public License - LGPLv2.1+). The provided binaries are official static builds free for use.